React

Utilisez des composants React préconstruits pour ajouter Docs Embed à votre application React

Pour les projets React, GitBook fournit des composants préconstruits qui facilitent l’intégration de votre documentation de manière simple et idiomatique. Les composants gèrent automatiquement la gestion d’état, le contexte et le cycle de vie.

Étapes

1

Installer le package

Ajouter @gitbook/embed à votre projet React :

npm install @gitbook/embed

Pour la référence API complète et le code source, voir le @gitbook/embed package sur GitHub.

2

Importer les composants React

Importer le GitBookProvider et GitBookFrame composants :

import {
  GitBookProvider,
  GitBookFrame,
} from "@gitbook/embed/react";

3

Envelopper votre application avec GitBookProvider

Ajoutez le provider à la racine de votre arbre de composants ou là où vous avez besoin de l’intégration :

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <YourAppContent />
    </GitBookProvider>
  );
}

4

Ajouter le composant GitBookFrame

Placez le composant frame là où vous souhaitez que l’intégration apparaisse :

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <div className="app">
        <YourAppContent />
        <GitBookFrame
          visitor={{
            token: 'your-jwt-token', // Facultatif : pour le contenu adaptatif ou l’accès authentifié
            unsignedClaims: { userId: '123' } // Facultatif : claims personnalisés pour des expressions dynamiques
          }}
        />
      </div>
    </GitBookProvider>
  );
}

5

Personnaliser l’intégration

Passez des props de configuration au composant frame :

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    tabs={['assistant', 'docs']}
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    suggestions={['What is GitBook?', 'How do I get started?']}
    actions={[
      {
        icon: 'circle-question',
        label: 'Contact Support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

6

Contrôler l’intégration avec le hook useGitBook

Utilisez le useGitBook hook pour interagir avec l’intégration de manière programmatique :

import { useGitBook } from "@gitbook/embed/react";

function HelpButton() {
  const gitbook = useGitBook();
  const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
  
  const handleNavigate = () => {
    const iframe = document.createElement('iframe');
    iframe.src = frameURL;
    const frame = gitbook.createFrame(iframe);
    frame.navigateToPage('/getting-started');
    frame.navigateToAssistant();
    frame.postUserMessage('How do I get started?');
  };

  return <button onClick={handleNavigate}>Get Help</button>;
}

7

Rendre l’intégration de façon conditionnelle

Afficher l’intégration uniquement lorsque c’est nécessaire :

function App() {
  const [showEmbed, setShowEmbed] = useState(false);

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>Get Help</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}

8

Utilisation avec Next.js ou rendu côté serveur

Importez dynamiquement les composants pour éviter les problèmes de SSR :

import dynamic from "next/dynamic";

const GitBookProvider = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookProvider),
  { ssr: false }
);

const GitBookFrame = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookFrame),
  { ssr: false }
);

Props & Configuration

Props de GitBookProvider :

Prop	Type	Obligatoire	Par défaut	Description
siteURL	string	Oui	N/A	L’URL du site de votre documentation GitBook (par ex., https://docs.company.com).
children	ReactNode	Oui	N/A	Composants enfants à rendre au sein du provider.

Props de GitBookFrame :

Toutes les options de configuration peuvent être passées en props à <GitBookFrame>. Consultez la section Configuration ci‑dessous pour les options disponibles.

Prop	Type	Obligatoire	Par défaut	Description
className	string	Non	null	Nom de classe CSS à appliquer au conteneur de la frame.
style	object	Non	{}	Styles en ligne à appliquer au conteneur de la frame.
visitor	object	Non	{}	Options d’accès authentifié (voir ci‑dessous).

Hook useGitBook :

Renvoie une GitBookClient instance avec les méthodes suivantes :

• getFrameURL(options?: { visitor?: {...} }) → string - Obtenir l’URL de l’iframe

• createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Créer un client de frame

Le client de frame fournit :

• navigateToPage(path: string) → void

• navigateToAssistant() → void

• postUserMessage(message: string) → void

• clearChat() → void

• configure(settings: {...}) → void

• on(event: string, listener: Function) → () => void

Options de configuration

Les options de configuration sont disponibles en tant que props sur <GitBookFrame>:

tabs

Remplace les onglets affichés. Par défaut, utilise la configuration de votre site.

• Type: ('assistant' | 'docs')[]

actions

Boutons d’action personnalisés rendus dans la barre latérale à côté des onglets. Chaque bouton d’action déclenche un rappel lorsqu’on clique dessus.

Remarque: Ceci s’appelait auparavant buttons. Utilisez actions à la place.

• Type: Array<{ icon: string, label: string, onClick: () => void }>

greeting

Message de bienvenue affiché dans l’onglet Assistant.

• Type: { title: string, subtitle: string }

suggestions

Questions suggérées affichées dans l’écran de bienvenue de l’Assistant.

• Type: string[]

tools

Outils IA personnalisés pour étendre l’Assistant. Voir Creating custom tools pour les détails.

• Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

visitor (Authenticated Access)

Utilisé pour Adaptive Content et Authenticated Access.

• Type: { token?: string, unsignedClaims?: Record<string, unknown> }

Pièges courants

• Ne pas envelopper avec GitBookProvider – Le GitBookFrame exige un parent GitBookProvider pour fonctionner.

• Utilisation avec SSR sans import dynamique – Le composant utilise des APIs du navigateur et doit être importé dynamiquement dans Next.js ou d’autres frameworks SSR.

• siteURL ne correspondant pas à la documentation publiée – Assurez‑vous que la propriété siteURL correspond exactement à l’URL de votre site de documentation en ligne.

• Appeler useGitBook en dehors du provider – Le useGitBook hook doit être utilisé au sein d’un composant qui est enfant de GitBookProvider.

• Plusieurs providers dans l’arbre – Évitez d’imbrquer plusieurs GitBookProvider instances, car cela peut provoquer des conflits de contexte.

• Utilisation d’anciens noms de composants – Le composant est maintenant GitBookFrame, pas GitBookAssistantFrame.