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',
  currency: 'EUR',
  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 la recherche produit de Dialog sur une storefront React custom ou headless : la même Search que derrière les blocs Shopify. 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, theme } = useDialogSearch({
    client,
    language: 'fr',
    currency: client.currency,
  })

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

useDialogSearch

Crée un search controller par instance du hook et le dispose au démontage. Renvoie { controller, state, theme } (theme est le thème du client, pour DialogSearchResults) : passez-les aux composants ci-dessous. state.status vaut idle / loading / success / empty / error.

Option	Type	Requis	Défaut	Description
client	Dialog	Oui	-	Instance SDK.
language	string	Oui	-	Code langue ISO 639-1 en minuscules de la recherche, par exemple 'fr'.
currency	string	Oui	-	Devise ISO 4217 de la recherche, par exemple client.currency.
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.
sections	SearchSection[]	Non	-	Index supplémentaires interrogés avec les produits, ex. [{ index: 'collections', hitsPerPage: 5 }] remplit la colonne collections. Ne demandez qu’un index exposé par le catalogue : un index absent fait échouer toute la 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 centré sur la barre (jusqu’à 1440px de large, remplissant le viewport) : placez-le juste après DialogSearchBar. Il reprend la mise en page de l’overlay de recherche Shopify : une colonne collections à gauche quand sections les demande, les produits à droite en liste ou en grille 3 colonnes, la correspondance de la requête mise en évidence dans chaque titre, et soit un bouton « Voir tous les résultats », soit la pagination. Sous 768px le panneau s’empile, collections en rail horizontal au-dessus des produits. Couleurs, arrondis et police suivent le thème SDK (palette sombre quand backgroundColor est sombre, angles droits ou arrondis selon ctaBorderType). 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 pour les prix, compteurs et libellés (libellés anglais et format numérique du navigateur si omise).
theme	Theme	Non	Le thème du client, tel que renvoyé par useDialogSearch ; stylise le panneau (palette, arrondis, police).
layout	'list' | 'grid'	Non	Disposition des produits.
seeAllHref	(query: string) => string	Non	Lien du bouton « Voir tous les résultats » en pied de panneau ; omis, le panneau pagine à la place.

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',
  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: { /* ... */ },
})

É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.