React
Use prebuilt React components to add the Docs Embed to your React application
Last updated
Was this helpful?
Use prebuilt React components to add the Docs Embed to your React application
Last updated
Was this helpful?
Was this helpful?
For React projects, GitBook provides prebuilt components that make embedding your docs simple and idiomatic. The components handle state management, context, and lifecycle automatically.
Add @gitbook/embed to your React project:
npm install @gitbook/embedFor the complete API reference and source code, see the @gitbook/embed package on GitHub.
Place the frame component where you want the embed to appear:
function App() {
return (
<GitBookProvider siteURL="https://docs.company.com">
<div className="app">
<YourAppContent />
<GitBookFrame
visitor={{
token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
unsignedClaims: { userId: '123' } // Optional: custom claims for dynamic expressions
}}
/>
</div>
</GitBookProvider>
);
}Pass configuration props to the frame component:
<GitBookProvider siteURL="https://docs.company.com">
<GitBookFrame
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={[/* ... */]}
visitor={{
token: 'your-jwt-token',
unsignedClaims: { userId: '123' }
}}
/>
</GitBookProvider>Use the useGitBook hook to interact with the embed programmatically:
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;
const frame = gitbook.createFrame(iframe);
frame.navigateToPage('/getting-started');
frame.navigateToAssistant();
frame.postUserMessage('How do I get started?');
};
return <button onClick={handleNavigate}>Get Help</button>;
}Show the embed only when needed:
function App() {
const [showEmbed, setShowEmbed] = useState(false);
return (
<GitBookProvider siteURL="https://docs.company.com">
<button onClick={() => setShowEmbed(true)}>Get Help</button>
{showEmbed && <GitBookFrame />}
</GitBookProvider>
);
}Dynamically import the components to avoid SSR issues:
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 }
);GitBookProvider Props:
siteURL
string
Yes
N/A
Your GitBook docs site URL (e.g., https://docs.company.com).
children
ReactNode
Yes
N/A
Child components to render within the provider.
GitBookFrame Props:
All configuration options can be passed as props to <GitBookFrame>. See the Configuration section below for available options.
className
string
No
null
CSS class name to apply to the frame container.
style
object
No
{}
Inline styles to apply to the frame container.
visitor
object
No
{}
Authenticated access options (see below).
useGitBook Hook:
Returns a GitBookClient instance with the following methods:
getFrameURL(options?: { visitor?: {...} }) β string - Get the iframe URL
createFrame(iframe: HTMLIFrameElement) β GitBookFrameClient - Create a frame client
The frame client provides:
navigateToPage(path: string) β void
navigateToAssistant() β void
postUserMessage(message: string) β void
clearChat() β void
configure(settings: {...}) β void
on(event: string, listener: Function) β () => void
Configuration options are available as props on <GitBookFrame>:
tabsOverride which tabs are displayed. Defaults to your site's configuration.
Type: ('assistant' | 'docs')[]
actionsCustom 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 }>
greetingWelcome message displayed in the Assistant tab.
Type: { title: string, subtitle: string }
suggestionsSuggested questions displayed in the Assistant welcome screen.
Type: string[]
toolsCustom AI tools to extend the Assistant. See Creating custom tools for details.
Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>
visitor (Authenticated Access)Used for Adaptive Content and Authenticated Access.
Type: { token?: string, unsignedClaims?: Record<string, unknown> }
Not wrapping with GitBookProvider β The GitBookFrame requires a parent GitBookProvider to function.
Using with SSR without dynamic import β The component uses browser APIs and must be dynamically imported in Next.js or other SSR frameworks.
siteURL not matching published docs β Ensure the siteURL prop matches your live docs site URL exactly.
Calling useGitBook outside provider β The useGitBook hook must be used within a component that's a child of GitBookProvider.
Multiple providers in the tree β Avoid nesting multiple GitBookProvider instances, as this can cause context conflicts.
Using old component names β The component is now GitBookFrame, not GitBookAssistantFrame.