> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/publier/embedding/implementation/react.md).

# 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

{% stepper %}
{% step %}
**Installer le paquet**

Ajoutez `@gitbook/embed` à votre projet React :

```bash
npm install @gitbook/embed
```

Pour la référence complète de l'API et le code source, consultez le [`@gitbook/embed` package sur GitHub](https://github.com/GitbookIO/gitbook/tree/main/packages/embed).
{% endstep %}

{% step %}
**Importez les composants React**

Importez le `GitBookProvider` et `GitBookFrame` components:

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

{% endstep %}

{% step %}
**Encapsulez votre application avec GitBookProvider**

Ajoutez le provider à la racine de l’arborescence de vos composants, ou à l’endroit où vous avez besoin de l’intégration :

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

{% endstep %}

{% step %}
**Ajoutez le composant GitBookFrame**

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

```jsx
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>
  );
}
```

{% hint style="info" %}
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. La version autonome [balise de script](/docs/documentation/fr/publier/embedding/implementation/script.md) l'ajoute automatiquement.
{% endhint %}
{% endstep %}

{% step %}
**Personnalisez l’intégration**

Passez des props de configuration au composant frame :

```jsx
<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="Support Copilot"
    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.
{% endstep %}

{% step %}
**Contrôlez l’intégration avec le hook useGitBook**

Utilisez la commande `useGitBook` hook pour interagir avec l’intégration par programmation :

```jsx
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>;
}
```

{% endstep %}

{% step %}
**Rendre l’intégration conditionnelle**

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

```jsx
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>
  );
}
```

{% endstep %}

{% step %}
**Utiliser avec Next.js ou le rendu côté serveur**

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

```jsx
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 }
);
```

{% endstep %}
{% endstepper %}

## Props et configuration

**Props de GitBookProvider :**

| Propriété  | Type        | Requis | 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 à l’intérieur du provider.                              |

**Props de GitBookFrame :**

Toutes les options de configuration peuvent être transmises comme props à `<GitBookFrame>`. Consultez la section Configuration ci-dessous pour les options disponibles.

| Propriété       | Type                | Requis | Par défaut                   | Description                                               |
| --------------- | ------------------- | ------ | ---------------------------- | --------------------------------------------------------- |
| `className`     | `string`            | Non    | `null`                       | Nom de classe CSS à appliquer au conteneur du frame.      |
| `style`         | `objet`             | Non    | `{}`                         | Styles inline à 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`                       | Affichez 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 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 comme props sur `<GitBookFrame>`:

### `tabs`

Remplacez les onglets affichés.

La recherche est activée par défaut. Si vous définissez `tabs`, l'intégration n'affiche que les onglets que vous listez.

* **Type**: `('assistant' | 'search' | 'docs')[]`

### `colorScheme`

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

Lorsqu'il est omis, l'intégration suit le CSS de l'iframe `color-scheme`, ce qui lui permet d'hériter de la page parente ou de la préférence du navigateur.

* **Type**: `'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**: C'était auparavant appelé `boutons`. Utilisez `actions` à la place.

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

### `message d'accueil`

Message de bienvenue affiché dans l'onglet Assistant.

* **Type**: `{ title: string, subtitle: string }`

### `assistantName`

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

* **Type**: `string`
* **Longueur maximale**: `32` caractères

### `closeButton`

Affichez un bouton de fermeture dans l'Assistant.

* **Type**: `booléen`

### `suggestions`

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

* **Type**: `string[]`

### `marque`

Affichez ou masquez la marque GitBook dans l'interface d'intégration — y compris le pied de page de l'intégration Docs et la marque de l'Assistant.

* **Type**: `booléen`
* **Par défaut**: `vrai`

### `outils`

Outils IA personnalisés pour étendre l'Assistant. Voir [Créer des outils personnalisés](/docs/documentation/fr/publier/embedding/configuration/creating-custom-tools.md) pour plus de détails.

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

### `visitor` (Accès authentifié)

Utilisé pour [Contenu adaptatif](/docs/documentation/fr/publier/adaptive-content.md) et [Accès authentifié](/docs/documentation/fr/publier/site-audience/authenticated-access.md).

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

## Pièges courants

* **Ne pas encapsuler avec GitBookProvider** – L' `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 d’autres frameworks SSR.
* **siteURL ne correspond pas à la documentation publiée** – Assurez-vous que la `siteURL` prop correspond exactement à l’URL de votre site de documentation en ligne.
* **Appel de useGitBook en dehors du provider** – L' `useGitBook` hook doit être utilisé à l’intérieur d’un composant qui est un enfant de `GitBookProvider`.
* **Plusieurs providers dans l’arborescence** – Évitez d’imbriquer plusieurs `GitBookProvider` instances, car cela peut provoquer des conflits de contexte.
* **Utilisation d’anciens noms de composants** – Le composant est maintenant `GitBookFrame`, et non `GitBookAssistantFrame`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/fr/publier/embedding/implementation/react.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.