Redoc vs Scalar: Which API Reference Renderer?

This guide is part of Scalar & Modern Docs Integration within Developer Portal Frameworks & UI Setup. It is a decision guide for teams choosing between Redoc and Scalar to render their API reference from an OpenAPI document. The choice matters because the two tools optimise for different jobs — Redoc for clean, fast, read-only reference, Scalar for an interactive experience with a built-in request console — and switching later means re-theming and re-deploying.

Redoc vs Scalar decision From one OpenAPI 3.1 spec, choosing read-only reference leads to Redoc, while needing an interactive request console leads to Scalar. openapi 3.1 spec Need live Try-It? Redoc read-only reference Scalar interactive client no yes

Problem & Context

You have an OpenAPI 3.1 document and need to publish reference docs. Both Redoc and Scalar take that document and produce a polished, navigable reference, and both ship a free open-source build and a one-line CDN embed — so a surface comparison makes them look interchangeable. They are not.

The decision that bites later is interactivity. The open-source Redoc renderer is deliberately read-only: it produces a fast, single-document reference with a three-pane layout and no request console. Scalar, by contrast, builds its identity around an interactive HTTP client embedded right next to each operation. If your developers need to fire real requests from the docs and you ship Redoc, you will be bolting on a proxy or migrating later. If you only need clean reference and you ship Scalar, you carry an interactive runtime you never use. The rest of this guide makes the trade-offs concrete and gives a working embed for each so you can prototype both.

Step-by-Step Solution

1. Compare on the criteria that actually differ

Criterion Redoc (open source) Scalar (open source)
Rendering model Single static three-pane document, read-optimised Operation list with inline interactive panels
Interactive HTTP client No — read-only; Try-It is a Redocly commercial feature Yes — built-in request console in the free build
OpenAPI 3.1 support Yes (JSON Schema 2020-12) Yes (JSON Schema 2020-12)
Theming theme object (typography, colours, spacing) CSS variables (--scalar-*) mapped to design tokens
Output Static HTML bundle via @redocly/cli build-docs Static bundle via @scalar/cli build or CDN embed
Hosting Any static host / CDN; self-host friendly Any static host / CDN; self-host friendly
Best fit Large read-heavy reference, long-form spec docs Interactive docs where readers send live requests
Dark mode Via theme overrides First-class, toggle + darkMode config

For deeper Redoc configuration — enterprise theming, nav grouping, and the Redocly platform features — see Redocly & OpenAPI UI Configuration.

2. Decide on interactivity first

This single question resolves most cases. If onboarding depends on developers calling endpoints from the page, choose Scalar — its console is free and needs no extra infrastructure. If your reference is consumed alongside SDKs or a separate sandbox, Redoc’s read-only model is lighter and faster.

3. Build a proof of concept for each

Render the same spec in both with a minimal HTML embed (below) and put them in front of two or three engineers. Judge load time, deep-link behaviour, and how the theming maps onto your design tokens — not the marketing pages.

Complete Working Example

A single self-contained HTML file per renderer, each pointing at the same openapi.yaml, so you can drop both into a /poc directory and compare side by side.

Redoc — read-only reference:

<!doctype html>
<!-- redoc-poc.html — open in a browser or serve statically -->
<html>
  <head>
    <meta charset="utf-8" />
    <title>Redoc POC</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <redoc spec-url="/openapi.yaml"></redoc>
    <!-- pin the major version: v2.x is current; the deprecated redoc-cli is gone -->
    <script src="https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js"></script>
  </body>
</html>

Scalar — interactive client:

<!doctype html>
<!-- scalar-poc.html — open in a browser or serve statically -->
<html>
  <head>
    <meta charset="utf-8" />
    <title>Scalar POC</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <script
      id="api-reference"
      data-url="/openapi.yaml"
      data-configuration='{"theme":"default","darkMode":true}'
      src="https://cdn.jsdelivr.net/npm/@scalar/api-reference/dist/browser/standalone.js"
    ></script>
  </body>
</html>

For production, replace the CDN tags with pinned, self-hosted builds: npx @redocly/cli build-docs openapi.yaml -o redoc.html for Redoc, and npx @scalar/cli build --input openapi.yaml --output dist/ for Scalar. Both emit static artifacts you deploy to any host.

Gotchas & Edge Cases

Assuming open-source Redoc has Try-It. The interactive request console is a Redocly platform feature, not part of the free redoc package. Teams that demo the commercial product and then deploy the open-source bundle are surprised by the missing console. If you need it without paying, Scalar is the open-source answer.

Malformed 3.1 specs degrade silently. Both renderers render what they can and quietly drop what they cannot parse, so an invalid $ref or a bad 2020-12 schema can vanish from the output with no error. Lint with @redocly/cli lint or @stoplight/spectral-cli in CI before either build.

Theming is not portable. Redoc themes via a structured theme object; Scalar themes via CSS variables. Migrating between them means re-authoring the theme from scratch — budget for it rather than expecting a config copy-paste.

FAQ

Does Redoc have a built-in Try-It HTTP client?

The open-source Redoc renderer is read-only and has no request console; the interactive Try-It console is part of Redocly’s commercial platform. Scalar ships an interactive HTTP client in its free open-source build.

Do both Redoc and Scalar support OpenAPI 3.1?

Yes, current versions of both render OpenAPI 3.1, including JSON Schema 2020-12 keywords. Validate the spec with a linter first, because both renderers degrade quietly on malformed 3.1 documents.

Which renders large specs faster?

Redoc is built for large, read-heavy specs and renders them efficiently as a single static document. Scalar handles large specs well too, but its interactive client adds runtime weight you do not need for pure reference reading.