Componentes React

@askdialog/dialog-react provee componentes listos para usar sobre @askdialog/dialog-sdk. Úsalo cuando quieras una UI rápida y temática sin construirla desde cero.

Requiere React 19+.

Install

npm install @askdialog/dialog-sdk @askdialog/dialog-react

Importa la stylesheet una vez en la entrada de tu app:

import '@askdialog/dialog-react/style.css'

Inicializar el cliente SDK

Instancia el SDK una vez (típicamente a nivel de módulo o en un provider top-level), luego pásalo a cada componente.

import { Dialog, type SimplifiedProduct } from '@askdialog/dialog-sdk'

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  currency: 'EUR',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId }) => {
      // Llama a tu API de carrito, refresca tu UI
    },
    getProduct: async (productId, variantId): Promise<SimplifiedProduct> => {
      // Devuelve tu producto con el formato SimplifiedProduct
    },
  },
})

Ver la Referencia del SDK para todas las opciones del constructor.

DialogProductBlock

El componente principal. Colócalo en una página de producto para renderizar sugerencias de preguntas generadas por IA y el punto de entrada al asistente.

import { DialogProductBlock } from '@askdialog/dialog-react'

function ProductPage({ product }) {
  return (
    <DialogProductBlock
      client={client}
      productId={product.id}
      productTitle={product.title}
      selectedVariantId={product.currentVariantId}
    />
  )
}

Props

Prop	Tipo	Requerido	Default	Descripción
client	Dialog	Sí	-	Instancia SDK desde new Dialog(...).
productId	string	Sí	-	El ID del producto mostrado. Debe matchear el ID en tu catálogo.
productTitle	string	Sí	-	Nombre mostrado del producto.
selectedVariantId	string	No	-	La variante seleccionada actualmente. Pásala cada vez que el usuario cambia de variante para que el asistente tenga el contexto.
enableInput	boolean	No	true	Muestra el campo input bajo las sugerencias. Pon false si quieres solo las sugerencias.

DialogInput

Un campo input autónomo para hacer una pregunta libre. Útil como punto de entrada en páginas sin contexto único de producto (homepage, blog, colección).

import { DialogInput } from '@askdialog/dialog-react'

function Homepage() {
  return (
    <DialogInput
      client={client}
      productId="homepage"
      productTitle="Homepage"
    />
  )
}

Props

Prop	Tipo	Requerido	Descripción
client	Dialog	Sí	Instancia SDK.
productId	string	Sí	Identificador estable del contexto (ej. "homepage", "collection-verano").
productTitle	string	Sí	Etiqueta legible del contexto.

Búsqueda en la storefront

Componentes listos para usar que impulsan la búsqueda de productos de Dialog en una storefront React custom o headless: la misma Search que hay detrás de los bloques Shopify. Envuelven el search controller del SDK (createSearchController): debounce, cancelación de peticiones, protección contra respuestas obsoletas, paginación y analytics de atribución vienen todos del SDK, así que los componentes solo renderizan y enrutan.

import {
  DialogSearchBar,
  DialogSearchResults,
  useDialogSearch,
} from '@askdialog/dialog-react'

function SearchPage() {
  const { controller, state, theme } = useDialogSearch({
    client,
    language: 'es',
    currency: client.currency,
  })

  return (
    <>
      <DialogSearchBar controller={controller} placeholder="Buscar productos..." />
      <DialogSearchResults controller={controller} state={state} theme={theme} />
    </>
  )
}

useDialogSearch

Crea un search controller por instancia del hook y lo dispose al desmontar. Devuelve { controller, state, theme } (theme es el theme del cliente, para DialogSearchResults): pásalos a los componentes de abajo. state.status es idle / loading / success / empty / error.

Opción	Tipo	Requerido	Default	Descripción
client	Dialog	Sí	-	Instancia SDK.
language	string	Sí	-	Código de idioma ISO 639-1 en minúsculas de la búsqueda, por ejemplo 'es'.
currency	string	Sí	-	Divisa ISO 4217 de la búsqueda, por ejemplo client.currency.
surface	SearchSurface	No	'search_page'	Dónde se muestran los resultados, para analytics.
navigate	(url, hit) => void	No	-	Adaptador de router llamado tras la atribución de la selección (ej. (url) => router.push(url)). Omítelo para dejar que los enlaces <a href> de las tarjetas naveguen de forma nativa.
debounceMs	number	No	250	Debounce de tecleo.
hitsPerPage	number	No	12	Resultados por página.
sections	SearchSection[]	No	-	Índices extra buscados junto a los productos, ej. [{ index: 'collections', hitsPerPage: 5 }] rellena la columna de colecciones. Pide solo un índice que el catálogo exponga: uno ausente hace fallar toda la búsqueda.

DialogSearchBar

Campo de búsqueda: teclear lanza una búsqueda con debounce, enviar (Enter) busca inmediatamente.

Prop	Tipo	Requerido	Default	Descripción
controller	SearchController	Sí	-	De useDialogSearch.
placeholder	string	No	-	Texto del placeholder.
autoFocus	boolean	No	false	Pone el foco en el campo al montar.
submitAriaLabel	string	No	'Search'	Etiqueta accesible del botón de envío.

DialogSearchResults

Panel de resultados flotante, portalizado en document.body y centrado en la barra (hasta 1440px de ancho, llenando el viewport): colócalo justo después de DialogSearchBar. Muestra el mismo layout que el overlay de búsqueda de Shopify: una columna de colecciones a la izquierda cuando sections las pide, los productos a la derecha en lista o en cuadrícula de 3 columnas, la coincidencia de la consulta resaltada en cada título, y o bien un botón «Ver todos los resultados» o bien la paginación. Por debajo de 768px el panel se apila, colecciones en un carril horizontal sobre los productos. Colores, radios y fuente siguen el theme del SDK (paleta oscura cuando backgroundColor es oscuro, esquinas rectas o redondeadas según ctaBorderType). Cada tarjeta enlaza a la página de producto y registra la atribución de búsqueda (impresiones, selección al clic y al clic central) automáticamente.

Prop	Tipo	Requerido	Descripción
controller	SearchController	Sí	De useDialogSearch.
state	SearchControllerState	Sí	De useDialogSearch.
locale	string	No	Locale BCP 47 para precios, contadores y etiquetas (etiquetas en inglés y formato numérico del navegador si se omite).
theme	Theme	No	El theme del cliente, tal como lo devuelve useDialogSearch; estiliza el panel (paleta, radios, fuente).
layout	'list' | 'grid'	No	Layout de los productos.
seeAllHref	(query: string) => string	No	Enlace del botón «Ver todos los resultados» al pie del panel; omitido, el panel pagina en su lugar.

DialogSearchPagination es renderizado por DialogSearchResults y también se exporta para layouts custom (mismas props controller + state).

Layout típico

Un setup común:

• <DialogInput> en la homepage como punto de entrada discovery.
• <DialogProductBlock> en cada PDP, entre la galería y la descripción.
• Un handler de cambio de variante que actualiza la prop selectedVariantId.

Theming

Los componentes heredan el theme pasado al constructor del SDK. Actualiza colores de marca, fuentes, forma de los CTA y tamaños de fuente específicos de los componentes:

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  currency: 'EUR',
  theme: {
    backgroundColor: '#ffffff',
    primaryColor: '#000000',
    ctaTextColor: '#ffffff',
    ctaBorderType: 'rounded',
    capitalizeCtas: false,
    fontFamily: 'Inter, sans-serif',
    title: { fontSize: '18px', color: '#1a1a1a' },
    description: { fontSize: '14px', color: '#666666' },
    content: { fontSize: '14px', color: '#333333' },
  },
  callbacks: { /* ... */ },
})

Siguientes pasos

• Referencia del SDK: API completa de client.
• Tracking: SDK custom: conecta el tracking side-cart y checkout.
• Problemas al añadir al carrito: mantener tu UI sincronizada.