Omnisearch

• Resultados en vivo que se muestran a tus visitantes a medida que escriben, e incluyen productos, categorías y páginas.
• Ordenar y filtrar: para que tus visitantes refinen su búsqueda de manera intuitiva y sencilla.
• Fácil de integrar en tu sitio usando una de nuestras excelentes plantillas iniciales.
• Se adapta a tu marca mediante el cambio de algunos ajustes estándar como logo, fuentes, colores y más.
• Totalmente personalizable con HTML, CSS y Liquid para desarrolladores.

Primeros pasos #

Omnisearch consiste en un Diseño personalizable para los elementos visuales y un bloque Elemento que permite instalarlo en tu sitio.

Creando un diseño #

Esto se realiza en Search > Designs > New Design

Selecciona el tipo Omnisearch, elige un diseño inicial y asígnale un nombre.

Haz clic en Save & Close para finalizar el diseño estándar.

Nuestros diseños estándar funcionan directamente y siempre pueden editarse más adelante. Editar requiere conocimiento de HTML, CSS y Liquid. Consulta Estilos en esta guía para más información.

Creando un Elemento #

Esto se realiza en Search > Element > New Element

Los bloques de Element son contenedores para los elementos que creas en tu cuenta my.clerk.io. Contienen la lógica para mostrar resultados y ajustes para la cantidad de resultados a mostrar. La lógica del estado vacío también puede ser manipulada mediante Rules.

• Nombre te ayuda a identificar tu elemento en caso de que desees crear más de uno. Puede ser modificado posteriormente.

• Tipo de Elemento es Omnisearch por defecto, y no debe cambiarse. Aquí también puedes agregar filtros si es necesario, pero en la mayoría de las configuraciones no es necesario.

• Lógica de Estado Vacío te permite seleccionar el tipo de productos a mostrar cuando Omnisearch se abre por primera vez, antes de que se introduzcan palabras. Por defecto es Bestsellers pero también puede ser personalizado, por ejemplo, con Visitor Recommendations.

Finalizar Diseño #

El diseño que renderizará el bloque Element. Selecciona el diseño que creaste.

Si tu diseño incluye variables, también pueden establecerse aquí.

Puedes controlar el número de resultados a mostrar para cada tipo, cada vez que se realiza una búsqueda. Generalmente recomendamos estas cantidades:

• Productos: 20-60
• Sugerencias: 5
• Categorías y páginas: 10

Finalmente, elige los atributos que deseas incluir como Facets y establece los nombres como aparecerán en los resultados de búsqueda. Si no puedes encontrar un atributo específico en la lista, agrégalo en la lista de “filterable attributes”, en Search Configuration.

Insertar en el sitio #

La Visibilidad se utiliza para controlar quién puede ver el Omnisearch.

• En vista previa te permite probar tu elemento sin afectar tu sitio en vivo. Puedes abrir tu sitio en modo de vista previa haciendo clic en “Open site in preview” o agregando ?clerk_content_mode=preview a la url de tu sitio.

• En mi sitio en vivo se usa cuando has terminado de probar y estás listo para hacerlo público.

Usando injection #

Esta es la forma más sencilla de instalar. Clerk añadirá automáticamente el código de Omnisearch a tu sitio, apuntando a un campo de búsqueda de tu elección, y activándose a partir de un evento.

• Evento controla lo que el usuario debe hacer para activar el Omnisearch. Lo más probable es que quieras que se muestre cuando tus visitantes hacen clic en tu icono de búsqueda o campo de entrada.

• Elemento decide la parte del sitio web con la que debe interactuar el usuario. Por ejemplo, si quieres que tu elemento Omnisearch se muestre solo cuando tus visitantes interactúan con tu barra de búsqueda (clic o enfoque sobre ella), solo necesitas encontrar el selector CSS único que se le aplica. Si tienes identificadores diferentes en móvil y escritorio, agrégalos ambos.

Encuentra tu selector CSS único de la siguiente manera:

1. Inspecciona el código de tu sitio. En la mayoría de los navegadores puedes hacer clic derecho en cualquier lugar de tu página y elegir Inspeccionar o similar.
2. Encuentra el elemento que deseas apuntar
3. Haz clic derecho sobre él y busca la opción copiar > copiar selector

Usando código embebido #

Si tienes cambios sin guardar, guárdalos para generar el código embebido.

Copia este código y pégalo en el archivo que genera todas las páginas de la tienda, idealmente cerca de la etiqueta de cierre </body>.

Reemplaza INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH con el selector CSS del elemento html que debería activar tu Omnisearch.

A continuación, un ejemplo completo de un embed code de Omnisearch con todas las opciones de configuración:

<span class="clerk"
    data-template="@omnisearch"
    data-api="search/omni"
    data-trigger-element="INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH"
    data-limit="40"
    data-suggestions="6"
    data-categories="6"
    data-pages="6"
    data-omni-search-suggestions="6"
    data-omni-search-categories="6"
    data-omni-search-pages="6"
    data-omni-search-empty="recommendations/popular">
</span>

Modos de visualización #

Omnisearch admite dos modos de visualización que controlan cómo aparece la interfaz de búsqueda en tu sitio. Configura esto en la pestaña Insert al editar tu Element Omnisearch.

Superposición completa #

Este es el modo por defecto. Cuando se activa, Omnisearch cubre toda la ventana con una superposición a pantalla completa. La interfaz de búsqueda ocupa toda la página, proporcionando una experiencia de búsqueda enfocada.

Utiliza este modo cuando desees:

• Un entorno de búsqueda sin distracciones
• Control total sobre la disposición de la búsqueda
• Que la interfaz de búsqueda sea completamente independiente del encabezado de tu sitio

Superposición parcial #

Este modo integra Omnisearch con el encabezado existente de tu sitio. En lugar de cubrir toda la pantalla, la superposición de búsqueda aparece debajo de tu encabezado manteniendo el encabezado visible y funcional.

Utiliza este modo cuando desees:

• Que tu encabezado y navegación permanezcan accesibles durante la búsqueda
• Una integración más fluida con el diseño actual de tu sitio
• Que la experiencia de búsqueda se sienta como una parte natural de tu sitio

Opciones de configuración #

Cuando se selecciona Superposición Parcial, se habilitan ajustes adicionales:

Selector de encabezado

El selector CSS para el elemento de encabezado de tu sitio. Omnisearch utiliza esto para posicionar la superposición directamente debajo de tu encabezado, asegurando la alineación adecuada.

Ejemplos de selectores:

• header
• .site-header
• #main-header

Selector de campo de búsqueda

El selector CSS para tu campo de búsqueda existente. Si se proporciona, Omnisearch se sincroniza con el campo de búsqueda de tu encabezado, creando una experiencia de búsqueda unificada donde al escribir en la caja de búsqueda del encabezado se actualizan los resultados en Omnisearch.

Ejemplos de selectores:

• #search-input
• .header-search input
• [name="search"]

Anchura

Controla el tamaño horizontal de la superposición:

• Ancho completo: Ocupa todo el ancho de la ventana
• Ancho de contenido: Coincide con el ancho de un elemento contenedor que especifiques mediante un selector CSS
• Ancho fijo: Un ancho de píxeles específico que definas

Altura

Controla el tamaño vertical de la superposición:

• Desde el encabezado hasta el fondo: Ocupa el espacio desde debajo del encabezado hasta la parte inferior de la ventana
• Porcentaje de la ventana: Un porcentaje de la altura de la ventana (por ejemplo, 80%)
• Altura fija: Una altura de píxeles específica
• Altura máxima: Establece un límite superior permitiendo que la superposición sea menor si el contenido requiere menos espacio

Alineación horizontal

Controla dónde aparece la superposición horizontalmente:

• Izquierda: Se alinea al lado izquierdo de la ventana
• Centro: Centra la superposición horizontalmente
• Derecha: Se alinea al lado derecho de la ventana

Posición vertical

Controla la ubicación vertical en relación al encabezado:

• Debajo del encabezado: Posiciona la superposición directamente debajo del elemento de encabezado
• Fijo desde arriba: Un desplazamiento en píxeles específico desde la parte superior de la ventana

Configuración del diseño #

La mayoría de Omni-search se puede configurar cambiando las variables que están en los archivos de diseño.

En el lenguaje de plantillas liquid, una variable tiene la siguiente estructura:

{% assign variable_name = "variable value" %}

Como regla general, solo debe cambiarse el valor de la variable para configurar el Omni-search.

Los usuarios más técnicos pueden, por supuesto, modificar líneas específicas de HTML y CSS, consulta esta sección.

Logo #

Para agregar el logo al diseño de Omni-search, simplemente encuentra la URL de la imagen y colócala en el valor de la variable: os_brand_logo.

La variable típicamente se llama algo como os_brand_logo, y debe verse así una vez que el logo ha sido pegado:

Carga infinita/automática #

Si quieres controlar si el Omni-search debe cargar más resultados de productos automáticamente, una vez que el usuario haya llegado a la última fila, la variable debe establecerse en true o false. Típicamente la variable se llama os_autoload. En este ejemplo, el Omni-search no carga automáticamente más resultados de productos.

Traducciones #

Por defecto, la plantilla está en inglés. Si tienes una tienda en otro idioma, puedes traducir los textos cambiando los valores de las variables.

Este ejemplo muestra las variables para el botón de ordenación:

Protip: Utiliza IA generativa (por ejemplo, chatGPT) para traducir en masa escribiendo “Traduce estos valores de variables de inglés a danés. Devuelve el código completo para que se pueda copiar/pegar y reemplazar el código existente: PASTE_VARIABLES_HERE”

Estilizado (Styling) #

Para cambiar cualquier estilo, la configuración se puede hacer en las variables de CSS.

Las plantillas usan variables CSS que tienen una estructura como la siguiente:

--variable_name: variable_value;

Para usuarios avanzados, se pueden modificar reglas CSS individuales para realizar cambios de diseño más complejos.

Colores #

Los colores configurables se pueden identificar y definir en la sección bajo el comentario de CSS “Colors” /* Colors */

Fuentes #

De manera similar a los colores, la variable de fuente se encuentra bajo el comentario /* Font */.

Normalmente tiene una variable como: --font-family: 'Kumbh Sans', sans serif;

Diseño estándar #

El diseño estándar para Omnisearch incluye:

• Soporte para menú desplegable de variantes: Permite a los compradores elegir atributos de variantes (ej. talla, color) antes de añadir al carrito.

• Selector de cantidad.

• Botón nativo de Añadir al Carrito que notifica a Clerk.js, garantizando que la analítica y el merchandising permanezcan sincronizados.

• Etiquetado limpio y bien estructurado con comentarios claros.

• Variables centralizadas para estilo y comportamiento, facilitando el ajuste de colores, espaciados, etiquetas y opciones comunes sin cambiar el código central.

• Facet de deslizador de precio para filtrado rápido por rango.

• Sugerencias clicables que activan inmediatamente una búsqueda.

Para desarrolladores #

Estilizado #

Los diseños consisten en un layout principal, estilos CSS y un conjunto de sub-diseños que pueden ser referenciados en el layout principal.

Puedes editar todo esto de manera separada para Escritorio y Móvil. Por defecto, el Omni-search utiliza el mismo HTML para todos los tamaños de pantalla, y emplea CSS para ser totalmente responsivo. Por esto la pestaña Mobile no tiene código al principio.

Si es necesario, puedes crear un marcado HTML completamente diferente para Móvil, que se usará en pantallas pequeñas.

Inicialmente puede que solo quieras ajustar unas pocas cosas para adaptar el diseño a la imagen de tu marca — Siempre puedes editar tu diseño más adelante.

HTML #

Este es el layout principal que controla la ubicación de todos los elementos. Utiliza Liquid como lenguaje de plantillas.

En nuestros diseños iniciales, la primera sección está dedicada a los elementos más comúnmente cambiados, como etiquetas de ordenación, moneda y los diferentes textos que puedes traducir a tu idioma.

CSS #

Estilos que serán inyectados junto con el HTML, dándote control total sobre el aspecto visual de manera contenida.

Sub-diseños disponibles #

Cualquier diseño añadido aquí puede ser referenciado en el layout general. Funcionan como módulos que se editan por separado y se agregan con su ID y nombre: {{@247373 - TopBarSearchForm}}

Puedes eliminar, duplicar y copiar la referencia de cualquier sub-diseño haciendo clic en el botón de tres puntos.

Para editar un sub-diseño, haz clic en su icono Edit. Una vez que termines de editar, haz clic en Save & close para volver al editor de layout principal.

Algunos elementos necesitan identificadores específicos, como:

• El campo de entrada id="clerk-omnisearch-input"
• El contenedor de contenido id="clerk-omnisearch-content"

Siempre que quieras comprobar tu progreso, puedes hacerlo haciendo clic en el botón “Preview design”.

Las personalizaciones más frecuentes en los diseños son estas:

• Logo: Accede a TopBarSearchForm y reemplaza el logo por el tuyo.

• Fuentes: Si es necesario, ajusta las fuentes para que coincidan con el estilo de tu sitio.

• Colores: Puedes incluir los colores de tu marca en los elementos que desees destacar o alinear con el resto del sitio como botones y etiquetas.

• Botones y bordes de etiquetas: Puedes ajustar su color, radio, anchura…

• Enlaces: Si tienes un estilo específico para tus enlaces, también puedes editarlo.

Partes reactivas vs estáticas #

Comprender qué partes de Omnisearch se vuelven a renderizar por consulta — y cuáles no — es importante al personalizar el diseño.

Partes estáticas se renderizan una vez cuando la superposición se abre y no se vuelven a tocar en consultas posteriores:

• El contenedor de la superposición (clerk-omnisearch-overlay)
• El campo de entrada de búsqueda (#clerk-omnisearch-input)
• Cualquier HTML en el diseño que esté fuera de #clerk-omnisearch-content — como el logo, botón de cerrar o barra superior

El campo de entrada es intencionalmente estático. Volver a renderizarlo en cada pulsación interrumpiría la escritura del visitante y rompería la experiencia de búsqueda.

Partes reactivas son todo lo que está dentro de #clerk-omnisearch-content. Todo este contenedor se vuelve a renderizar con cada consulta:

• Resultados de productos
• Facets y filtros
• Categorías, páginas y sugerencias
• Contadores de resultados y controles de ordenación
• Mensajes de no resultados

Si deseas que un elemento se actualice cuando cambia la consulta — por ejemplo, un contador de resultados en vivo en el encabezado — debe estar dentro de #clerk-omnisearch-content. Si deseas que permanezca visible y estable mientras el visitante escribe, colócalo fuera de ese contenedor.

Estado Sin Resultados #

Cuando una consulta de búsqueda no devuelve productos, Omnisearch no muestra automáticamente un recurso alternativo — esto se controla en el diseño usando Liquid.

El enfoque recomendado es verificar si no hay productos y condicionalmente mostrar un deslizador alternativo y un mensaje personalizado:

{% if products.length > 0 %}
  <!-- Resultados normales -->
  {% for product in products %}
    <!-- tarjeta de producto -->
  {% endfor %}

{% else %}
  <!-- Sin resultados, recurso alternativo -->
  <div class="clerk-no-results-message">
    No hay resultados para "{{ query }}" — aquí tienes algunas opciones populares:
  </div>

  <span class="clerk"
    data-api="recommendations/popular"
    data-limit="8"
    data-template="@omnisearch-product-card">
  </span>
{% endif %}

También puedes usar results.products.no_exact_match para detectar cuando Omnisearch muestra coincidencias difusas o relacionadas en lugar de resultados exactos, y mostrar un mensaje adecuado:

{% if results.products.no_exact_match %}
  <div class="clerk-no-exact-match">
    No hay resultados exactos para "{{ query }}" — mostrando coincidencias más cercanas:
  </div>
{% endif %}

Ambos patrones pueden combinarse. Una configuración habitual muestra el mensaje no_exact_match en línea encima de los resultados, y el deslizador alternativo solo cuando products.length == 0.

El texto del mensaje de sin resultados es HTML simple dentro del diseño, así que puede traducirse o estilizarse libremente sin cambiar ninguna configuración fuera del editor de diseño.

Estructura de la superposición #

Cuando se inicia omnisearch, se crea un elemento con la clase clerk-omnisearch-overlay y se inyecta al final del body.

Aquí es donde inyectaremos el diseño, ya que tenemos el campo de entrada como parte del diseño, necesitamos ciertos requisitos estructurales para que no se vuelva a renderizar el campo de entrada cada vez. La estructura debe verse así debajo de la superposición:

<div>
    <input type="text" id="clerk-omnisearch-input"/>
    <div id="clerk-omnisearch-content">
        Element!
    </div>
</div>

Campo de entrada #

Para encontrar el campo de entrada necesita tener el identificador clerk-omnisearch-input. Una vez que se dispara el elemento desencadenante, movemos el foco del cursor a este elemento, y se agrega cualquier consulta que tengamos, para mantener la experiencia del usuario lo más fluida posible.

Contenedor de contenido #

El contenedor de contenido es donde ocurren la mayoría de las cosas, el contenedor que lo rodea debe tener el identificador clerk-omnisearch-content. Aquí deben situarse los facets, los sliders y todo lo que no sea el campo de entrada.

Clases #

Puede añadirse funcionalidad al diseño agregando clases específicas a los elementos.

Botón de Cerrar #

clerk-omnisearch-close

Al adjuntar la clase a un elemento dentro del diseño, ese elemento ocultará la superposición.

Ordenar #

clerk-omnisearch-sort

Encuentra menús desplegables de ordenación y les añade eventos.

Para que funcione un elemento de ordenación en el diseño, agrégalo al elemento seleccionador, por ejemplo, un menú desplegable. El elemento debe ser en la forma value:[desc|asc], es decir, el valor a ordenar, seguido de dos puntos y luego desc o asc. Opcionalmente puedes agregar un atributo data-sort-type si quieres ordenarlo por categorías o páginas.

Facet de búsqueda #

clerk-facet-search

Si hay una búsqueda en facets, crea un evento y oculta facets que no coincidan con la consulta.

La clase, cuando está presente en una página, verifica la existencia de elementos de búsqueda de facets. Las búsquedas de facets proporcionan una forma para que los usuarios busquen en los facets. Para que funcione, el elemento debe tener un valor de cadena.

Borrado total #

clerk-omnisearch-full-reset

Al hacer clic, los elementos con la clase borrarán todos los facets seleccionados y resetearán la consulta.

Borrado de facets #

clerk-omnisearch-facet-full-reset

Al hacer clic, los elementos con la clase deseleccionarán todos los facets activos. Esto normalmente se ve en un botón de estilo ‘Borrar todo’ dentro de un grupo de facets, permitiendo a los usuarios resetear sus filtros seleccionados de forma sencilla.

Borrado de grupo #

clerk-omnisearch-facet-group-reset

Al hacer clic, los elementos con esta clase deseleccionarán todos los elementos hijos dentro del grupo.

Para ofrecer la función de deseleccionar un grupo completo de facets, un elemento puede tener la clase correspondiente. Una vez que el elemento se activa (por ejemplo, al hacer clic), todos los elementos dentro de su grupo se deseleccionan, reiniciando ese grupo de facets. Para que funcione, el elemento debe tener el grupo que se quiere borrar como atributo con el nombre data-facet-group.

Borrado de facet único #

clerk-omnisearch-facet-reset

Los elementos con esta clase deben deseleccionar un solo elemento con el par de atributos grupo/valor dado.

Esta clase está diseñada para casos en los que es necesario deseleccionar un solo facet. Un elemento con la clase puede asociarse a un facet específico de un grupo dándole tanto un data-facet-group como un data-facet-value. Al activarlo, solo deseleccionará su facet asociado en base al par grupo/valor dado, dejando los demás facets seleccionados sin cambios.

Click en facet #

clerk-facet

Los elementos con esta clase se tratarán como facets seleccionables.

Todos los facets deben tener la clase, con los atributos data-facet-group y data-facet-value para identificar la opción elegida por el cliente.