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.
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>
);
To see it in action, click here:
Docusaurus uses this component to catch errors within the theme's layout, and also within the entire app.
This component doesn't catch build-time errors and only protects against client-side render errors that can happen when using stateful React components.
Props
fallback
: an optional render callback returning a JSX element. It will receive an object with 2 attributes:error
, the error that was caught, andtryAgain
, 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.
The fallback
prop is a callback, and not a React functional component. You can't use React hooks inside this callback.
<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:
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:
<Parent>
<Head>
<title>My Title</title>
<meta name="description" content="Helmet application" />
</Head>
<Child>
<Head>
<title>Nested Title</title>
<meta name="description" content="Nested component" />
</Head>
</Child>
</Parent>
Outputs:
<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"
.
import React from 'react';
import Link from '@docusaurus/Link';
const Page = () => (
<div>
<p>
Check out my <Link to="/blog">blog</Link>!
</p>
<p>
Follow me on <Link to="https://twitter.com/docusaurus">Twitter</Link>!
</p>
</div>
);
to
: string
The target location to navigate to. Example: /docs/introduction
.
<Link to="/courses" />
Prefer this component to vanilla <a>
tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use <Link>
.
<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:
import React from 'react';
import {Redirect} from '@docusaurus/router';
const Home = () => {
return <Redirect to="/docs/test" />;
};
@docusaurus/router
implements React Router and supports its features.
<BrowserOnly/>
The <BrowserOnly>
component permits to render React components only in the browser after the React app has hydrated.
Use it for integrating with code that can't run in Node.js, because the window
or document
objects are being accessed.
Props
children
: render function prop returning browser-only JSX. Will not be executed in Node.jsfallback
(optional): JSX to render on the server (Node.js) and until React hydration completes.
Example with code
import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = () => {
return (
<BrowserOnly>
{() => <span>page url = {window.location.href}</span>}
</BrowserOnly>
);
};