# Use Redoc CE React component

## Before you begin

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:

```bash
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:

```bash
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.

## Build API documentation

1. Import the `RedocStandalone` component.

  ```js
  import { RedocStandalone } from 'redoc';
  ```
2. Use the component, either:

    - link to your description with a URL:

      ```jsx
      <RedocStandalone specUrl="https://redocly.github.io/redoc/cafe.yaml" />
      ```
    - pass your description as an object:

      ```jsx
      <RedocStandalone spec={definitionObject} />
      ```
    - pass a GraphQL schema as an SDL string:

      ```jsx
      <RedocStandalone spec={schemaSdl} />
      ```
  `specUrl` accepts AsyncAPI documents and GraphQL schema files as well.
  See [Supported specifications](/docs/redoc/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](/docs/redoc/config) in the `options` prop to alter how it renders.

  For example:

  ```jsx
  <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.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| specUrl | string | URL or root-relative path of the OpenAPI, AsyncAPI, or GraphQL description. Ignored when `spec` is provided. |
| spec | object \| string | Parsed description object, a JSON string of the description, or a GraphQL schema in SDL. |
| options | [Options object](/docs/redoc/config) | Configuration options. |
| basePath | string | Path the documentation is mounted at, used to build route URLs. Default: `/`. |
| logo | object | Sidebar logo as `{ url, href, altText, backgroundColor }`. Defaults to the `x-logo` extension in the `info` object of the description. |
| onLoaded | function | Called once the description is loaded, or with an `Error` as the first argument when loading fails. |
| children | ReactNode | Rendered while the description loads, instead of the default spinner. |

## Routing

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.

## Specify `onLoaded` callback

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.

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

## Display a placeholder while loading

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.

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

## Disable telemetry

Redoc CE sends anonymous [usage telemetry](/docs/redoc/telemetry) by default.
To turn it off, set `disableTelemetry` in the `options` prop, like any other option:

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

## Low-level API

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.

```jsx
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}
    />
  );
}
```

### Write your own Markdown adapter

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

| Function | Type | Description |
| --- | --- | --- |
| parse | function | **REQUIRED.** Receives a description: a Markdown string, or a description that `prepareApiDocs` has already parsed into a Markdoc tree. Returns the value that `render` receives. |
| render | function | **REQUIRED.** Receives the value that `parse` returned. Returns React elements, a string, or `null`. A Markdoc tree is not a React element: render it first, for example with `Markdoc.renderers.react(tree, React)`. |

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.

## Resources

- **[Redoc CE deployment guide](/docs/redoc/deployment/intro)** - Step-by-step instructions for setting up your Redoc CE project
- **[Configure Redoc CE](/docs/redoc/config)** - Every option you can pass in the `options` prop
- **[Telemetry in Redoc CE](/docs/redoc/telemetry)** - What Redoc CE collects and how to turn it off
