# 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

{% stepper %}
{% step %}

#### Install the package

Add `@gitbook/embed` to your project:

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

For the complete API reference and source code, see the [`@gitbook/embed` package on GitHub](https://github.com/GitbookIO/gitbook/tree/main/packages/embed).
{% endstep %}

{% step %}

#### Import the package

In your application code, import the `createGitBook` function:

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

Or using CommonJS:

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

{% endstep %}

{% step %}

#### Initialize GitBook

Create a GitBook instance with your docs site URL:

```javascript
const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});
```

{% endstep %}

{% step %}

#### Create an iframe

Generate an iframe element and set its source to the embed URL:

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

{% endstep %}

{% step %}

#### Attach the frame

Create a GitBook frame instance and mount it to your page:

```javascript
const frame = gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);
```

{% endstep %}

{% step %}

#### Control the embed programmatically

Use the frame instance to interact with the embed:

```javascript
// 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();
```

{% endstep %}

{% step %}

#### Configure the embed

Configure the embed with customization options:

```javascript
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?' },
  suggestions: ['What is GitBook?', 'How do I get started?'],
  tools: [/* ... */]
});
```

{% endstep %}

{% step %}

#### Listen to events

Register event listeners to respond to embed events:

```javascript
frame.on('close', () => {
  console.log('Frame closed');
});

// Unsubscribe when done
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigated to:', data.path);
});
```

{% endstep %}
{% endstepper %}

## 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 }`

#### `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](/docs/docs-site/embedding/configuration/creating-custom-tools.md) for details.

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

### 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](/docs/site-access/adaptive-content.md) and [Authenticated Access](/docs/site-access/authenticated-access.md).

* **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.


---

# Agent Instructions: 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:

```
GET https://gitbook.com/docs/docs-site/embedding/implementation/nodejs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.