Use Redoc CE React component

Redoc CE is published as the redoc package and renders with the React of your application. Your project must already use react and react-dom 18.3 or 19.

Install the package together with its other peer dependencies:

npm install redoc styled-components react-router @redocly/config

React Router 8 requires React 19.2.7 or later. With React 18, or React 19 earlier than 19.2.7, install React Router 7:

npm install redoc styled-components react-router@7 @redocly/config

The package ships as an ES module and requires Node.js 22 or later for your build tooling.

1. Import the RedocStandalone component.

   import { RedocStandalone } from 'redoc';
   

2. Use the component, either:

   • link to your description with a URL:

     <RedocStandalone specUrl="https://redocly.github.io/redoc/cafe.yaml" />
     

   • pass your description as an object:

     <RedocStandalone spec={definitionObject} />
     

   • pass a GraphQL schema as an SDL string:

     <RedocStandalone spec={schemaSdl} />
     

   specUrl accepts AsyncAPI documents and GraphQL schema files as well. See Supported specifications. To load a description file from your own project, place it in the folder your build tool serves as static assets. For example, public in Vite or in Next.js. Then point specUrl at its root-relative path such as /openapi.yaml. The file is fetched at runtime, so a file that is not served as a static asset fails to load. To bundle the description with your application instead, import a JSON description and pass it to spec.

3. (Optional) Pass configuration options in the options prop to alter how it renders.

   For example:

   <RedocStandalone
     specUrl="https://redocly.github.io/redoc/cafe.yaml"
     options={{
       sortRequiredPropsFirst: true,
       schemaDefinitionsTagName: 'Schemas',
       hideDownloadButtons: true,
     }}
   />
   

RedocStandalone loads and bundles the description, converts Swagger 2.0 documents to OpenAPI 3, and renders the documentation with the sidebar and search. While the description loads, it displays a spinner. The spinner does not render if you set hideLoading: true in options or pass your own placeholder as children. When loading fails, it renders a Failed to load API description message with the underlying error.

Redoc CE builds deep links with React Router. When RedocStandalone renders outside a React Router context, it creates a browser router, so routes are path-based: with basePath="/docs", an operation page is /docs/products/listmenuitems. Your server must return the application for every path under basePath.

When your application already provides a router, Redoc CE reuses it. Wrap the component in a HashRouter to get hash-based URLs like the standalone HTML element.

You can also specify the onLoaded callback. It is called when Redoc CE has loaded the description, or with an error as the first argument when loading fails. It is called again each time spec, specUrl, or basePath changes.

<RedocStandalone
  specUrl="https://redocly.github.io/redoc/cafe.yaml"
  onLoaded={(error) => {
    if (!error) {
      console.log('Yay!');
    }
  }}
/>

To display your own content while the description loads, pass it as children of RedocStandalone. When loading completes, Redoc CE replaces the children with the documentation.

<RedocStandalone specUrl="https://redocly.github.io/redoc/cafe.yaml">
  <p>Loading the API description…</p>
</RedocStandalone>

Redoc CE sends anonymous usage telemetry by default. To turn it off, set disableTelemetry in the options prop, like any other option:

<RedocStandalone
  specUrl="https://redocly.github.io/redoc/cafe.yaml"
  options={{ disableTelemetry: true }}
/>

The package also exports the building blocks behind RedocStandalone. Use them when your application needs to prepare the documentation model itself, for example to render it on a server:

• prepareApiDocs({ specUrl, spec, options, basePath }) loads and bundles the description and resolves to { items, store, options, specType, document }.
• Redoc renders a prepared model without the sidebar and search: <Redoc items={items} store={store} options={options} basePath={basePath} markdownAdapter={adapter} />. It requires a markdownAdapter that turns the description fields into React elements.
• createMarkdocAdapter() returns the Markdown adapter that RedocStandalone uses. Pass it to Redoc to render descriptions the same way.
• convertSwagger2OpenAPI(document) converts a Swagger 2.0 document to OpenAPI 3.
• ServerStyleSheet is re-exported from styled-components. Server rendering collects styles from the same instance the components use.

Create the adapter once, outside the component, so descriptions are not parsed again on every render. If you set the sanitize option, pass your options to it, createMarkdocAdapter(options), so descriptions rendered on demand are sanitized too.

import { useEffect, useState } from 'react';
import { Redoc, createMarkdocAdapter, prepareApiDocs } from 'redoc';

const markdownAdapter = createMarkdocAdapter();

function PreparedDocs() {
  const [prepared, setPrepared] = useState(null);

  useEffect(() => {
    prepareApiDocs({ specUrl: '/openapi.yaml', basePath: '/docs' }).then(setPrepared);
  }, []);

  if (!prepared) return <p>Preparing…</p>;

  return (
    <Redoc
      items={prepared.items}
      store={prepared.store}
      options={prepared.options}
      basePath="/docs"
      markdownAdapter={markdownAdapter}
    />
  );
}

To render descriptions with your own Markdown engine, pass an object with these two functions as markdownAdapter:

When parse or render is not a function, Redoc displays an error page instead of the documentation, and its error details name the missing function. When render returns an object that React cannot render, such as a Markdoc tree, the descriptions do not render, and the browser console shows an error that explains what render must return.

• Redoc CE deployment guide - Step-by-step instructions for setting up your Redoc CE project
• Configure Redoc CE - Every option you can pass in the options prop
• Telemetry in Redoc CE - What Redoc CE collects and how to turn it off