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 rendent l'intégration de votre documentation simple et idiomatique. Les composants gèrent automatiquement l'état, le contexte et le cycle de vie.

Étapes

1

Installez le package

Ajoutez @gitbook/embed dans votre projet React :

npm install @gitbook/embed

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

2

Importez les composants React

Importez le GitBookProvider et GitBookFrame components:

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

3

Enveloppez votre application avec GitBookProvider

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

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

4

Ajoutez le composant GitBookFrame

Placez le composant frame à l'endroit 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 : revendications personnalisées pour les expressions dynamiques
          }}
        />
      </div>
    </GitBookProvider>
  );
}

Si vous utilisez l’onglet Assistant, définissez allow="clipboard-write" sur l'iframe qui affiche l'intégration. Les intégrations React laissent la configuration de l'iframe à votre application. Le composant autonome balise script autonome l’ajoute automatiquement.

5

Personnalisez l'intégration

Passez les props de configuration au composant frame :

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    tabs={['assistant', 'search', 'docs']}
    colorScheme="dark"
    greeting={{ title: 'Bienvenue !', subtitle: 'Comment puis-je vous aider ?' }}
    assistantName="Copilote de support"
    closeButton={true}
    suggestions={['Qu'est-ce que GitBook ?', 'Comment puis-je commencer ?']}
    actions={[
      {
        icon: 'circle-question',
        label: 'Contacter le support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

Si vous omettez colorScheme, l'intégration suit le CSS de l'iframe color-scheme. Cela lui permet de correspondre automatiquement au thème de votre application.

6

Contrôlez l'intégration avec le hook useGitBook

Utilisez la useGitBook hook pour interagir avec l'intégration par programmation :

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;
    iframe.allow = 'clipboard-write';
    const frame = gitbook.createFrame(iframe);
    frame.navigateToPage('/getting-started');
    frame.navigateToAssistant();
    frame.postUserMessage('Comment puis-je commencer ?');
  };

  return <button onClick={handleNavigate}>Obtenir de l'aide</button>;
}

7

Rendez l'intégration conditionnelle

Affichez 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)}>Obtenir de l'aide</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}

8

Utilisation avec Next.js ou le 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 et configuration

Props de GitBookProvider :

Propriété	Tapez	Obligatoire	Par défaut	Description
siteURL	string	Oui	N/A	L'URL de votre site de documentation GitBook (par ex., https://docs.company.com).
children	ReactNode	Oui	N/A	Composants enfants à rendre dans le provider.

Props de GitBookFrame :

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

Propriété	Tapez	Obligatoire	Par défaut	Description
className	string	Non	null	Nom de la classe CSS à appliquer au conteneur du frame.
style	objet	Non	{}	Styles en ligne à appliquer au conteneur du frame.
colorScheme	'light' | 'dark'	Non	Hérite du CSS color-scheme	Remplacez le jeu de couleurs de l’intégration.
assistantName	string	Non	null	Remplacez le nom de l’assistant affiché dans l’interface.
closeButton	booléen	Non	null	Affiche un bouton de fermeture dans l’Assistant.
visitor	objet	Non	{}	Options d'accès authentifié (voir ci-dessous).

Hook useGitBook :

Retourne une GitBookClient instance avec les méthodes suivantes :

• getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) → string - Obtenir l'URL de l'iframe
• createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Créer un client de frame

Le client du frame fournit :

• navigateToPage(path: string) → vide
• navigateToAssistant() → vide
• postUserMessage(message: string) → vide
• clearChat() → vide
• configure(settings: {...}) → vide
• on(event: string, listener: Function) → () => void

Options de configuration

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

les onglets

Remplacez les onglets affichés.

La recherche est activée par défaut. Si vous définissez les onglets, l’embed n’affiche que les onglets que vous listez.

• Tapez: ('assistant' | 'search' | 'docs')[]

colorScheme

Remplacez le jeu de couleurs de l’intégration.

Lorsqu’elle est omise, l’intégration suit le CSS de l’iframe color-scheme, ce qui lui permet d’hériter du parent de la page ou de la préférence du navigateur.

• Tapez: 'light' | 'dark'

actions

Boutons d’action personnalisés affichés dans la barre latérale à côté des onglets. Chaque bouton d’action déclenche un rappel lorsqu’il est cliqué.

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

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

greeting

Message de bienvenue affiché dans l’onglet Assistant.

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

assistantName

Remplacez le nom de l’assistant affiché dans l’interface.

• Tapez: string
• Longueur maximale: 32 caractères

closeButton

Affiche un bouton de fermeture dans l’Assistant.

• Tapez: booléen

suggestions

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

• Tapez: string[]

marque déposée

Afficher ou masquer la marque GitBook dans l’interface de l’intégration — y compris le pied de page de l’intégration Docs et l’image de marque de l’Assistant.

• Tapez: booléen
• Par défaut: vrai

tools

Outils d’IA personnalisés pour étendre l’Assistant. Voir Création d’outils personnalisés pour plus de détails.

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

visitor (Accès authentifié)

Utilisé pour Contenu adaptatif et Accès authentifié.

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

Pièges courants

• Ne pas envelopper avec GitBookProvider – L’option GitBookFrame nécessite un parent GitBookProvider pour fonctionner.
• Utilisation avec SSR sans import dynamique – Le composant utilise des API du navigateur et doit être importé dynamiquement dans Next.js ou dans d'autres frameworks SSR.
• siteURL ne correspondant pas à la documentation publiée – Assurez-vous que le siteURL prop corresponde exactement à l'URL de votre site de documentation en ligne.
• Appeler useGitBook en dehors du provider – L’option useGitBook le hook doit être utilisé dans un composant qui est un enfant de GitBookProvider.
• Plusieurs providers dans l'arbre – Évitez d'imbriquer plusieurs GitBookProvider instances, car cela peut provoquer des conflits de contexte.
• Utilisation d'anciens noms de composants – Le composant est désormais GitBookFrame, et non GitBookAssistantFrame.