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',
  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 una búsqueda de productos rankeada por IA en una storefront React custom o headless: la misma búsqueda que hay detrás de los bloques Shopify AI Search. 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 } = useDialogSearch({ client })

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

useDialogSearch

Crea un search controller por instancia del hook y lo dispose al desmontar. Devuelve { controller, state }: pasa ambos 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.
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.
locale	string	No	-	Locale reenviado a la petición de 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 anclado bajo la barra: colócalo justo después de DialogSearchBar. Renderiza los estados del controller; una búsqueda exitosa muestra una lista scrolleable de tarjetas de producto más la paginación. 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 usada para formatear los precios de las tarjetas (default del navegador si se omite).

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',
  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.