Composants React

@askdialog/dialog-react fournit des composants prêts à l’emploi par-dessus @askdialog/dialog-sdk. Utilisez-le quand vous voulez une UI rapide et thémée sans la construire de zéro.

Requiert React 19+.

Install

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

Importez la feuille de style une fois à l’entrée de votre app :

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

Initialiser le client SDK

Instanciez le SDK une fois (typiquement au scope module ou dans un provider top-level), puis passez-le à chaque composant.

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

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId }) => {
      // Appelez votre API panier, refresh votre UI
    },
    getProduct: async (productId, variantId): Promise<SimplifiedProduct> => {
      // Renvoyez votre produit au format SimplifiedProduct
    },
  },
})

Voir la Référence SDK pour toutes les options du constructor.

DialogProductBlock

Le composant principal. Posez-le sur une page produit pour render les suggestions de questions générées par l’IA et le point d’entrée vers l’assistant.

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

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

Props

Prop	Type	Requis	Défaut	Description
client	Dialog	Oui	-	Instance SDK depuis new Dialog(...).
productId	string	Oui	-	L’ID du produit affiché. Doit matcher l’ID dans votre catalogue.
productTitle	string	Oui	-	Nom affiché du produit.
selectedVariantId	string	Non	-	La variante actuellement sélectionnée. Passez-la chaque fois que l’utilisateur change de variante pour que l’assistant ait le contexte.
enableInput	boolean	Non	true	Affiche le champ de saisie sous les suggestions. Mettez à false si vous voulez seulement les suggestions.

DialogInput

Un champ de saisie autonome pour poser une question libre. Utile comme point d’entrée sur les pages sans contexte produit unique (homepage, blog, collection).

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

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

Props

Prop	Type	Requis	Description
client	Dialog	Oui	Instance SDK.
productId	string	Oui	Identifiant stable du contexte (ex. "homepage", "collection-ete").
productTitle	string	Oui	Label lisible du contexte.

Recherche storefront

Des composants prêts à l’emploi qui alimentent une recherche produit classée par l’IA sur une storefront React custom ou headless : la même recherche que derrière les blocs Shopify AI Search. Ils encapsulent le search controller du SDK (createSearchController) : debounce, annulation de requête, protection contre les réponses périmées, pagination et analytics d’attribution viennent tous du SDK, les composants ne font que render et router.

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

function SearchPage() {
  const { controller, state } = useDialogSearch({ client })

  return (
    <>
      <DialogSearchBar controller={controller} placeholder="Rechercher des produits..." />
      <DialogSearchResults controller={controller} state={state} />
    </>
  )
}

useDialogSearch

Crée un search controller par instance du hook et le dispose au démontage. Renvoie { controller, state } (passez les deux aux composants ci-dessous). state.status vaut idle / loading / success / empty / error.

Option	Type	Requis	Défaut	Description
client	Dialog	Oui	-	Instance SDK.
surface	SearchSurface	Non	'search_page'	Où les résultats sont affichés, pour l’analytics.
navigate	(url, hit) => void	Non	-	Adaptateur de routeur appelé après l’attribution de la sélection (ex. (url) => router.push(url)). Omettez-le pour laisser les liens <a href> des cartes naviguer nativement.
debounceMs	number	Non	250	Debounce de frappe.
hitsPerPage	number	Non	12	Résultats par page.
locale	string	Non	-	Locale transmise à la requête de recherche.

DialogSearchBar

Champ de recherche : la frappe lance une recherche debouncée, la soumission (Entrée) recherche immédiatement.

Prop	Type	Requis	Défaut	Description
controller	SearchController	Oui	-	Depuis useDialogSearch.
placeholder	string	Non	-	Texte du placeholder.
autoFocus	boolean	Non	false	Met le focus sur le champ au montage.
submitAriaLabel	string	Non	'Search'	Libellé accessible du bouton de soumission.

DialogSearchResults

Panneau de résultats flottant, portalé sur document.body et ancré sous la barre : placez-le juste après DialogSearchBar. Il render les états du controller ; une recherche réussie affiche une liste scrollable de cartes produit plus la pagination. Chaque carte renvoie vers la page produit et enregistre l’attribution de recherche (impressions, sélection au clic et au clic-milieu) automatiquement.

Prop	Type	Requis	Description
controller	SearchController	Oui	Depuis useDialogSearch.
state	SearchControllerState	Oui	Depuis useDialogSearch.
locale	string	Non	Locale BCP 47 utilisée pour formater les prix des cartes (défaut navigateur si omise).

DialogSearchPagination est rendu par DialogSearchResults et est aussi exporté pour les layouts custom (mêmes props controller + state).

Layout typique

Un setup courant :

• <DialogInput> sur la homepage comme point d’entrée discovery.
• <DialogProductBlock> sur chaque PDP, entre la galerie et la description.
• Un handler de changement de variante qui met à jour la prop selectedVariantId.

Theming

Les composants héritent du thème passé au constructor SDK. Mettez à jour les couleurs de marque, les polices, la forme des CTA, et les tailles de police spécifiques aux composants :

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  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: { /* ... */ },
})

Étapes suivantes

• Référence SDK : API complète de client.
• Tracking SDK custom : câblez le tracking side-cart et checkout.
• Problèmes d’ajout au panier : garder votre UI synchro.