GitBook Docs Embed (@gitbook/embed)

Embed your GitBook docs in your product or website.

The Docs Embed can contain two tabs:
- Assistant: The GitBook Assistant - an AI-powered chat interface to help users find answers
- Docs: A browser for navigating your documentation site

The embed is set up automatically based on your site's configuration. You can optionally customize and override the configuration with custom actions, tools, suggested questions, Authenticated Access, and more. See the Configuration section for all available options.

Usage

As a standalone script from your docs site

All GitBook docs sites include a script to easily add the Docs Embed as a widget on your website.

The script is served at https://docs.company.com/~gitbook/embed/script.js.

You can find the embed script from your docs site settings, or you can copy the following and replace docs.company.com with your docs site hostname.

``html


`

The standalone script provides a global GitBook function. See the API Reference section for all available methods.

$3

`javascript
GitBook('configure', {
button: {
label: 'Ask',
icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
},
tabs: ['assistant', 'docs'],
actions: [
{
icon: 'circle-question',
label: 'Contact Support',
onClick: () => window.open('https://support.example.com', '_blank')
}
],
greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
suggestions: ['What is GitBook?', 'How do I get started?'],
tools: [/ ... /]
});
`

See the Configuration section for all available options.

As a package from NPM

Install the package: npm install @gitbook/embed and import it in your web application:

`tsx
import { createGitBook } from '@gitbook/embed';

const gitbook = createGitBook({
siteURL: 'https://docs.company.com'
});

// Create an iframe and get its URL
const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL({
visitor: {
token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
unsignedClaims: { // Optional: custom claims for dynamic expressions
userId: '123',
plan: 'premium'
}
}
});

// Create a frame client to communicate with the iframe
const frame = gitbook.createFrame(iframe);

// Use the frame client methods
frame.navigateToPage('/getting-started'); // Navigate to a page in the docs tab
frame.navigateToAssistant(); // Switch to the assistant tab
frame.postUserMessage('How do I get started?');
frame.clearChat();

// Configure the embed (see Configuration section for all options)
frame.configure({
tabs: ['assistant', 'docs'],
actions: [
{
icon: 'circle-question',
label: 'Contact Support',
onClick: () => window.open('https://support.example.com', '_blank')
}
],
greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
suggestions: ['What is GitBook?', 'How do I get started?'],
tools: [/ ... /]
});

// Listen to events
frame.on('close', () => {
console.log('Frame closed');
});
`

As React components

After installing the NPM package, you can import prebuilt React components:

`tsx
import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';


visitor={{
token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
unsignedClaims: { userId: '123' } // Optional: custom claims for dynamic expressions
}}
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={[/ ... /]}
/>

`

You can also use the useGitBook hook to access the client:

`tsx
import { useGitBook } from '@gitbook/embed/react';

function MyComponent() {
const gitbook = useGitBook();
const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
// ...
}
`

API Reference

Method Comparison

| Method | Standalone Script | NPM Package | React Components |
|--------|------------------|-------------|------------------|
| Initialize | GitBook('init', options, frameOptions) | createGitBook(options) | |
| Get frame URL | ❌ (handled internally) | client.getFrameURL(options) | useGitBook().getFrameURL(options) |
| Create frame client | ❌ (handled internally) | client.createFrame(iframe) | useGitBook().createFrame(iframe) |
| Show/Hide widget | GitBook('show') / GitBook('hide') | ❌ | ❌ |
| Open/Close window | GitBook('open') / GitBook('close') / GitBook('toggle') | ❌ | ❌ |
| Navigate to page | GitBook('navigateToPage', path) | frame.navigateToPage(path) | Via frame client |
| Navigate to assistant | GitBook('navigateToAssistant') | frame.navigateToAssistant() | Via frame client |
| Post message | GitBook('postUserMessage', message) | frame.postUserMessage(message) | Via frame client |
| Clear chat | GitBook('clearChat') | frame.clearChat() | Via frame client |
| Configure | GitBook('configure', settings) | frame.configure(settings) | Props on |
| Event listeners | ❌ | frame.on(event, listener) | Via frame client |
| Unload | GitBook('unload') | ❌ | ❌ |

Method Signatures

$3

- GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - Initialize widget
- GitBook('show') - Show widget button
- GitBook('hide') - Hide widget button
- GitBook('open') - Open widget window
- GitBook('close') - Close widget window
- GitBook('toggle') - Toggle widget window
- GitBook('navigateToPage', path: string) - Navigate to page
- GitBook('navigateToAssistant') - Navigate to assistant tab
- GitBook('postUserMessage', message: string) - Post message to chat
- GitBook('clearChat') - Clear chat history
- GitBook('configure', settings: {...}) - Configure widget
- GitBook('unload') - Unload widget

$3

Client Factory:
- createGitBook(options: { siteURL: string }) → GitBookClient
- client.getFrameURL(options?: { visitor?: {...} }) → string
- client.createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient

Frame Client:
- frame.navigateToPage(path: string) → void
- frame.navigateToAssistant() → void
- frame.postUserMessage(message: string) → void
- frame.clearChat() → void
- frame.configure(settings: Partial) → void
- frame.on(event: string, listener: Function) → () => void (unsubscribe)

$3

Components:
- - Provider component
- - Frame component (accepts all config options as props)

Hooks:
- useGitBook() → GitBookClient (must be used within )

Configuration

Configuration options are available across usage methods as follows:
- Standalone script: via GitBook('configure', {...})
- NPM package: via frame.configure({...})
- React components: via props on

$3

Available in: Standalone script, NPM package, React components

Override which tabs are displayed. Defaults to your site's configuration.

- Type: ('assistant' | 'docs')[]
- Options:
- ['assistant', 'docs'] - Show both tabs
- ['assistant'] - Show only the assistant tab
- ['docs'] - Show only the docs tab

`javascript
tabs: ['assistant', 'docs']
`

$3

Available in: Standalone script, NPM package, React components

Custom action buttons rendered in the sidebar alongside tabs. Each action button triggers a callback when clicked.

Note: This prop was previously named buttons. Use actions instead, it has the same functionality.

- Type: GitBookEmbeddableActionDefinition[]
- Properties:
- icon: string - Icon name. Any FontAwesome icon is supported. (e.g., 'rocket', 'comments', 'user-circle', ...)
- label: string - Button label text
- onClick: () => void | Promise - Callback function when clicked

`javascript
actions: [
{
icon: 'comments',
label: 'Contact Support',
onClick: () => window.open('https://support.example.com', '_blank')
},
{
icon: 'rocket',
label: 'Get started',
onClick: () => {
GitBook('navigateToPage', '/getting-started');
}
}
]
`

$3

Available in: Standalone script, NPM package, React components

Welcome message displayed in the Assistant tab.

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

`javascript
greeting: {
title: 'Welcome!',
subtitle: 'How can I help you today?'
}
`

$3

Available in: Standalone script, NPM package, React components

Suggested questions displayed in the Assistant welcome screen.

- Type: string[]

`javascript
suggestions: [
'What is GitBook?',
'How do I get started?',
'What can you do?'
]
`

$3

Available in: Standalone script, NPM package, React components

Custom AI tools to extend the Assistant. Tools allow the assistant to execute functions and integrate with your own systems.

Note: In addition to custom tools, the Assistant will always have access to any MCP servers you define in your site's AI settings.

- Type: GitBookToolDefinition[]
- Properties:
- name: string - Unique tool identifier
- description: string - Description of what the tool does (used by the AI to decide when and how to use it).
- inputSchema: object - JSON schema defining the tool's input parameters
- execute: (input: object) => Promise<{ output: any, summary: string }> - Async function that executes the tool.
- output: The result of the tool execution, provided to the AI to continue working with. Not shown to the user.
- summary: The visual summary of the tool execution, shown in the user's chat window.
- confirmation: { icon?: string, label: string } (optional) - Confirmation button shown before execution, useful for actions that require the user's express approval.

`javascript
tools: [
{
name: 'get_user_info',
description: 'Get information about the current user',
inputSchema: {
type: 'object',
properties: {
userId: {
type: 'string',
description: 'The user ID to look up'
}
},
required: ['userId']
},
execute: async (input) => {
const user = await fetch(/api/users/${input.userId}).then(r => r.json());
return {
output: { name: user.name, plan: user.plan },
summary: Retrieved info for user ${user.name}
};
}
},
{
name: 'create_ticket',
description: 'Create a support ticket',
confirmation: {
icon: 'circle-question',
label: 'Create support ticket?'
},
inputSchema: {
type: 'object',
properties: {
subject: { type: 'string' },
description: { type: 'string' }
},
required: ['subject', 'description']
},
execute: async (input) => {
const ticket = await fetch('/api/tickets', {
method: 'POST',
body: JSON.stringify(input)
}).then(r => r.json());
return {
output: { ticketId: ticket.id },
summary: Created ticket #${ticket.id}
};
}
}
]
`

$3

Available in: Standalone script (via init), NPM package (via getFrameURL()), React components (as prop)

Authenticated Access options passed when creating the frame URL. Used for Adaptive Content and Authenticated Access.

Note: This is not a configuration option but rather a parameter when initializing the frame or creating the frame URL.

Standalone script: Pass as the second argument to GitBook('init', options, frameOptions)
NPM package: Pass to getFrameURL({ visitor: {...} })
React components: Pass as the visitor prop on

- Type: { token?: string, unsignedClaims?: Record }
- Properties:
- token: string (optional) - Signed JWT token for Adaptive Content or Authenticated Access
- unsignedClaims: Record (optional) - Unsigned claims that can be used in dynamic expressions via visitor.claims.unsigned.

`javascript
visitor: {
token: 'your-jwt-token',
unsignedClaims: {
userId: '123',
plan: 'premium',
role: 'admin'
}
}
`

$3

Available in: Standalone script only

Configure the widget button for the standalone script. This option is not available when using the NPM package or React components, since they can be customized completely.

- Type: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
- Properties:
- label: string - Button label text
- icon: 'assistant' | 'sparkle' | 'help' | 'book' - Icon displayed on the button. Choose from one of 4 presets.

`javascript
button: {
label: 'Ask',
icon: 'assistant'
}
``