Docusaurus Client API

Docusaurus provides some APIs on the clients that can be helpful to you when building your site.

Components

`<ErrorBoundary />`

This component creates a React error boundary.

Use it to wrap components that might throw, and display a fallback when that happens instead of crashing the whole app.

JSX

import React from 'react';
import ErrorBoundary from '@docusaurus/ErrorBoundary';

const SafeComponent = () => (
  <ErrorBoundary
    fallback={({error, tryAgain}) => (
      <div>
        <p>This component crashed because of error: {error.message}.</p>
        <button onClick={tryAgain}>Try Again!</button>
      </div>
    )}>
    <SomeDangerousComponentThatMayThrow />
  </ErrorBoundary>
);

mdx-code-block

import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton'

Props

fallback: an optional render callback returning a JSX element. It will receive an object with 2 attributes: error, the error that was caught, and tryAgain, a function (() => void) callback to reset the error in the component and try rendering it again. If not present, @theme/Error will be rendered instead. @theme/Error is used for the error boundaries wrapping the site, above the layout.

`<Head/>`

This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around React Helmet.

Usage Example:

JSX

import React from 'react';import Head from '@docusaurus/Head';const MySEO = () => (  <Head>    <meta property="og:description" content="My custom description" />    <meta charSet="utf-8" />    <title>My Title</title>    <link rel="canonical" href="http://mysite.com/example" />  </Head>);

Nested or latter components will override duplicate usages:

JSX

<Parent>
  {/* highlight-start */}
  <Head>
    <title>My Title</title>
    <meta name="description" content="Helmet application" />
  </Head>
  {/* highlight-end */}
  <Child>
    {/* highlight-start */}
    <Head>
      <title>Nested Title</title>
      <meta name="description" content="Nested component" />
    </Head>
    {/* highlight-end */}
  </Child>
</Parent>

Outputs:

HTML

<head>
  <title>Nested Title</title>
  <meta name="description" content="Nested component" />
</head>

`<Link/>`

This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an IntersectionObserver to fetch a low-priority request when the <Link> is in the viewport and then use an onMouseOver event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.

The component is a wrapper around react-router’s <Link> component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s <Link> component.

External links also work, and automatically have these props: target="_blank" rel="noopener noreferrer".

JSX

import React from 'react';import Link from '@docusaurus/Link';const Page = () => (  <div>    <p>      {/* highlight-next-line */}      Check out my <Link to="/blog">blog</Link>!    </p>    <p>      {/* highlight-next-line */}      Follow me on <Link to="https://x.com/docusaurus">X</Link>!    </p>  </div>);

`to`: string

The target location to navigate to. Example: /docs/introduction.

JSX

<Link to="/courses" />

`<Redirect/>`

Rendering a <Redirect> will navigate to a new location. The new location will override the current location in the history stack like server-side redirects (HTTP 3xx) do. You can refer to React Router's Redirect documentation for more info on available props.

Example usage:

JSX

import React from 'react';import {Redirect} from '@docusaurus/router';const Home = () => {  return <Redirect to="/docs/test" />;};

`<BrowserOnly/>`

The <BrowserOnly> component permits to render React components only in the browser after the React app has hydrated.

Props

children: render function prop returning browser-only JSX. Will not be executed in Node.js
fallback (optional): JSX to render on the server (Node.js) and until React hydration completes.

Example with code

JSX

import BrowserOnly from '@docusaurus/BrowserOnly';const MyComponent = () => {  return (    <BrowserOnly>      {() => <span>page url = {window.location.href}</span>}    </BrowserOnly>  );};

Example with a library

JSX

import BrowserOnly from '@docusaurus/BrowserOnly';const MyComponent = (props) => {  return (    <BrowserOnly fallback={<div>Loading...</div>}>      {() => {        const LibComponent = require('some-lib').LibComponent;        return <LibComponent {...props} />;      }}    </BrowserOnly>  );};

`<Interpolate/>`

A simple interpolation component for text containing dynamic placeholders.

The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...).

Props

children: text containing interpolation placeholders like {placeholderName}
values: object containing interpolation placeholder values

JSX

import React from 'react';import Link from '@docusaurus/Link';import Interpolate from '@docusaurus/Interpolate';export default function VisitMyWebsiteMessage() {  return (    <Interpolate      values={{        firstName: 'Sébastien',        website: (          <Link to="https://docusaurus.io" className="my-website-class">            website          </Link>        ),      }}>      {'Hello, {firstName}! How are you? Take a look at my {website}'}    </Interpolate>  );}

`<Translate/>`

When localizing your site, the <Translate/> component will allow providing translation support to React components, such as your homepage. The <Translate> component supports interpolation.

The translation strings will statically extracted from your code with the docusaurus write-translations CLI and a code.json translation file will be created in website/i18n/[locale].

Props

children: untranslated string in the default site locale (can contain interpolation placeholders)
id: optional value to be used as the key in JSON translation files
description: optional text to help the translator
values: optional object containing interpolation placeholder values

Example

src/pages/index.js

import React from 'react';import Layout from '@theme/Layout';import Translate from '@docusaurus/Translate';export default function Home() {  return (    <Layout>      <h1>        {/* highlight-start */}        <Translate          id="homepage.title"          description="The homepage welcome message">          Welcome to my website        </Translate>        {/* highlight-end */}      </h1>      <main>        {/* highlight-start */}        <Translate values={{firstName: 'Sébastien'}}>          {'Welcome, {firstName}! How are you?'}        </Translate>        {/* highlight-end */}      </main>    </Layout>  );}

Hooks

`useDocusaurusContext`

React hook to access Docusaurus Context. The context contains the siteConfig object from docusaurus.config.js and some additional site metadata.

TypeScript

type PluginVersionInformation =
  | {readonly type: 'package'; readonly version?: string}
  | {readonly type: 'project'}
  | {readonly type: 'local'}
  | {readonly type: 'synthetic'};

type SiteMetadata = {
  readonly docusaurusVersion: string;
  readonly siteVersion?: string;
  readonly pluginVersions: Record<string, PluginVersionInformation>;
};

type I18nLocaleConfig = {
  label: string;
  direction: string;
};

type I18n = {
  defaultLocale: string;
  locales: [string, ...string[]];
  currentLocale: string;
  localeConfigs: Record<string, I18nLocaleConfig>;
};

type DocusaurusContext = {
  siteConfig: DocusaurusConfig;
  siteMetadata: SiteMetadata;
  globalData: Record<string, unknown>;
  i18n: I18n;
  codeTranslations: Record<string, string>;
};

Usage example:

JSX

import React from 'react';import useDocusaurusContext from '@docusaurus/useDocusaurusContext';const MyComponent = () => {  const {siteConfig, siteMetadata} = useDocusaurusContext();  return (    <div>      {/* highlight-start */}      <h1>{siteConfig.title}</h1>      <div>{siteMetadata.siteVersion}</div>      <div>{siteMetadata.docusaurusVersion}</div>      {/* highlight-end */}    </div>  );};

`useIsBrowser`

Returns true after initial hydration completes in the browser.

Use this hook instead of typeof window !== 'undefined' in React rendering logic.

The initial render output must be consistent between server and client — components should not depend on browser-only state during the initial render. See The Perils of Rehydration.

useIsBrowser() and typeof window !== 'undefined' serve different purposes:

useIsBrowser() — tracks hydration state. Use it to gate UI behavior that should only activate after initial hydration.
typeof window !== 'undefined' — detects the runtime environment. Use it when you need to check DOM availability outside of React rendering logic.

Context	`useIsBrowser()`	`typeof window !== 'undefined'`
Node.js / SSR	`false`	`false`
During initial client render	`false`	`true` (DOM is available)
After initial hydration	`true`	`true`

Usage example:

JSX

import React from 'react';
import useIsBrowser from '@docusaurus/useIsBrowser';

const MyComponent = () => {
  const isBrowser = useIsBrowser();
  return <div>{isBrowser ? 'Browser' : 'Server'}</div>;
};

`useBaseUrl`

React hook to prepend your site baseUrl to a string.

Options

TypeScript

type BaseUrlOptions = {
  forcePrependBaseUrl: boolean;
  absolute: boolean;
};

Example usage:

JSX

import React from 'react';import useBaseUrl from '@docusaurus/useBaseUrl';const SomeImage = () => {  const imgSrc = useBaseUrl('/img/myImage.png');  return <img src={imgSrc} />;};

`useBaseUrlUtils`

Sometimes useBaseUrl is not good enough. This hook return additional utils related to your site's base URL.

withBaseUrl: useful if you need to add base URLs to multiple URLs at once.

JSX

import React from 'react';import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';const Component = () => {  const urls = ['/a', '/b'];  const {withBaseUrl} = useBaseUrlUtils();  const urlsWithBaseUrl = urls.map(withBaseUrl);  return <div>{/* ... */}</div>;};

`useGlobalData`

React hook to access Docusaurus global data created by all the plugins.

Global data is namespaced by plugin name then by plugin ID.

TypeScript

type GlobalData = Record<
  PluginName,
  Record<
    PluginId, // "default" by default
    any // plugin-specific data
  >
>;

Usage example:

JSX

import React from 'react';import useGlobalData from '@docusaurus/useGlobalData';const MyComponent = () => {  const globalData = useGlobalData();  const myPluginData = globalData['my-plugin']['default'];  return <div>{myPluginData.someAttribute}</div>;};

`usePluginData`

Access global data created by a specific plugin instance.

This is the most convenient hook to access plugin global data and should be used most of the time.

pluginId is optional if you don't use multi-instance plugins.

TypeScript

function usePluginData(
  pluginName: string,
  pluginId?: string,
  options?: {failfast?: boolean},
);

Usage example:

JSX

import React from 'react';import {usePluginData} from '@docusaurus/useGlobalData';const MyComponent = () => {  const myPluginData = usePluginData('my-plugin');  return <div>{myPluginData.someAttribute}</div>;};

`useAllPluginInstancesData`

Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.

TypeScript

function useAllPluginInstancesData(
  pluginName: string,
  options?: {failfast?: boolean},
);

Usage example:

JSX

import React from 'react';import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';const MyComponent = () => {  const allPluginInstancesData = useAllPluginInstancesData('my-plugin');  const myPluginData = allPluginInstancesData['default'];  return <div>{myPluginData.someAttribute}</div>;};

`useBrokenLinks`

React hook to access the Docusaurus broken link checker APIs, exposing a way for a Docusaurus pages to report and collect their links and anchors.

Usage example:

MyHeading.js

import useBrokenLinks from '@docusaurus/useBrokenLinks';

export default function MyHeading(props) {
  useBrokenLinks().collectAnchor(props.id);
  return <h2 {...props} />;
}

MyLink.js

import useBrokenLinks from '@docusaurus/useBrokenLinks';

export default function MyLink(props) {
  useBrokenLinks().collectLink(props.href);
  return <a {...props} />;
}

Functions

`interpolate`

The imperative counterpart of the <Interpolate> component.

Signature

TypeScript

// Simple string interpolation
function interpolate(text: string, values: Record<string, string>): string;

// JSX interpolation
function interpolate(
  text: string,
  values: Record<string, ReactNode>,
): ReactNode;

Example

JavaScript

import {interpolate} from '@docusaurus/Interpolate';const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});

`translate`

The imperative counterpart of the <Translate> component. Also supporting placeholders interpolation.

Signature

TypeScript

function translate(
  translation: {message: string; id?: string; description?: string},
  values: Record<string, string>,
): string;

Example

src/pages/index.js

import React from 'react';import Layout from '@theme/Layout';import {translate} from '@docusaurus/Translate';export default function Home() {  return (    <Layout      title={translate({message: 'My page meta title'})}>      <img        src={'https://docusaurus.io/logo.png'}        aria-label={          translate(            {              message: 'The logo of site {siteName}',              // Optional              id: 'homepage.logo.ariaLabel',              description: 'The home page logo aria label',            },            {siteName: 'Docusaurus'},          )        }      />    </Layout>  );}

Modules

`ExecutionEnvironment`

A module that exposes a few boolean variables to check the current rendering environment.

Example:

JavaScript

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  require('lib-that-only-works-client-side');
}

Field	Description
`ExecutionEnvironment.canUseDOM`	`true` if on client/browser, `false` on Node.js/prerendering.
`ExecutionEnvironment.canUseEventListeners`	`true` if on client and has `window.addEventListener`.
`ExecutionEnvironment.canUseIntersectionObserver`	`true` if on client and has `IntersectionObserver`.
`ExecutionEnvironment.canUseViewport`	`true` if on client and has `window.screen`.

`constants`

A module exposing useful constants to client-side theme code.

JavaScript

import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';

Named export	Value
`DEFAULT_PLUGIN_ID`	`default`

Components

<ErrorBoundary />

Props

<Head/>

<Link/>

to: string

<Redirect/>

<BrowserOnly/>

Props

Example with code

Example with a library

<Interpolate/>

Props

<Translate/>

Props

Example

Hooks

useDocusaurusContext

useIsBrowser

useBaseUrl

Options

Example usage:

useBaseUrlUtils

useGlobalData

usePluginData

useAllPluginInstancesData

useBrokenLinks

Functions

interpolate

Signature

Example

translate

Signature

Example

Modules

ExecutionEnvironment

constants

`<ErrorBoundary />`

`<Head/>`

`<Link/>`

`to`: string

`<Redirect/>`

`<BrowserOnly/>`

`<Interpolate/>`

`<Translate/>`

`useDocusaurusContext`

`useIsBrowser`

`useBaseUrl`

`useBaseUrlUtils`

`useGlobalData`

`usePluginData`

`useAllPluginInstancesData`

`useBrokenLinks`

`interpolate`

`translate`

`ExecutionEnvironment`

`constants`