Node.js/NPM

If you need more control and want to work at the application level, you can install the GitBook embed package from npm. This approach is ideal for server-side rendering, build-time integration, or custom iframe management.

Steps

npminstall@gitbook/embed

import{createGitBook}from"@gitbook/embed";

const{createGitBook}=require("@gitbook/embed");

constgitbook=createGitBook({
siteURL:"https://docs.company.com",
});

constiframe=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'
}
}
});
iframe.id="gitbook-embed-container";
iframe.style.border="none";
iframe.style.width="100%";
iframe.style.height="600px";

constframe=gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);

// Navigate to a specific page in the docs tab
frame.navigateToPage("/getting-started");
// Switch to the assistant tab
frame.navigateToAssistant();
// Post a message to the chat
frame.postUserMessage("How do I get started?");
// Clear chat history
frame.clearChat();

frame.configure({
trademark:false,
tabs: ['assistant','search','docs'],
actions: [
{
icon:'circle-question',
label:'Contact Support',
onClick:()=>window.open('https://support.example.com','_blank')
}
 ],
greeting:{title:'Welcome!',subtitle:'How can I help?'},
assistantName:'Support Copilot',
closeButton:true,
suggestions: ['What is GitBook?','How do I get started?'],
tools: [/* ... */]
});

frame.on('close',()=>{
console.log('Frame closed');
});
// Unsubscribe when done
constunsubscribe=frame.on('navigate',(data)=>{
console.log('Navigated to:',data.path);
});

API Reference

Client Factory

• createGitBook(options: { siteURL: string }) → GitBookClient

• client.getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) → string - Get the iframe URL with optional frame options

• client.createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Create a frame client to communicate with the iframe

Frame Client Methods

• frame.navigateToPage(path: string) → void - Navigate to a specific page in the docs tab

• frame.navigateToAssistant() → void - Switch to the assistant tab

• frame.postUserMessage(message: string) → void - Post a message to the chat

• frame.clearChat() → void - Clear chat history

• frame.configure(settings: Partial<GitBookEmbeddableConfiguration>) → void - Configure the embed

• frame.on(event: string, listener: Function) → () => void - Register event listener (returns unsubscribe function)

Configuration Options

Most customization options are available via frame.configure({...}).

tabs

Override which tabs are displayed.

Search is enabled by default. If you set tabs, the embed shows only the tabs you list.

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

actions

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

Note: This was previously named buttons. Use actions instead.

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

greeting

Welcome message displayed in the Assistant tab.

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

assistantName

Override the assistant name shown in the UI.

• Type: string

• Max length: 32 characters

closeButton

Display a close button inside the Assistant.

• Type: boolean

suggestions

Suggested questions displayed in the Assistant welcome screen.

• Type: string[]

trademark

Show or hide the GitBook trademark in the embed UI — including the Docs Embed footer and Assistant branding.

• Type: boolean

• Default: true

tools

Custom AI tools to extend the Assistant. See Creating custom tools for details.

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

Frame URL options

Some options are passed to getFrameURL({...}).

colorScheme

Override the embed color scheme.

When omitted, the embed follows the iframe's CSS color-scheme, which lets it inherit the parent page or browser preference.

• Type: 'light' | 'dark'

visitor (Authenticated Access)

Pass to getFrameURL({ visitor: {...} }). Used for Adaptive Content and Authenticated Access .

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

Common pitfalls

• Forgetting to install the package – Run npm install @gitbook/embed before importing.

• Missing siteURL – The siteURL option is required and must match your published docs site.

• iFrame not rendering – Ensure the parent container has sufficient width/height for the iframe to display.

• Frame methods called before initialization – Wait until createFrame() completes before calling frame methods.

• Not unsubscribing from events – Remember to call the unsubscribe function returned by frame.on() to prevent memory leaks.

• Using old API methods – Methods like open(), close(), toggle(), and destroy() are not available in the NPM package. Use the frame client methods instead.