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.

The comparison narrows quickly once you name the constraints. Both renderers read the same OpenAPI document and produce a good reference, so a feature-by-feature comparison rarely settles anything. Three constraints do most of the deciding, and each of them eliminates one option outright rather than scoring it lower.

The first is whether you need a request console in the free, self-hosted configuration. If a reader pressing Send is part of the experience you are committing to, that requirement alone narrows the field before anything else is considered.

The second is whether the reference must work with nothing fetched at load — behind a firewall, on an air-gapped network, from a file share. A build that inlines the renderer and the resolved specification into one artifact satisfies that; anything that resolves a specification in the browser does not.

The third is how much customization you intend to sustain. A renderer with a documented theme object supports a bounded set of changes indefinitely; reaching past that surface into generated class names works today and breaks silently on the next minor upgrade, in either tool.

The three deciding constraints Whether a free self-hosted console is required, whether the reference must work with nothing fetched at load, and how much customization will be sustained. answer these three and the choice usually makes itself 1. try-it console needed in the free, self-hosted setup? eliminates rather than scores 2. offline delivery must it work with nothing fetched at load? firewall and air-gap cases 3. customization budget what will you sustain across upgrades? be honest, not aspirational

Whichever you choose, the specification is unaffected. That is the reassuring part of this decision and worth saying plainly: both renderers read the same document, so choosing one does not commit the contract to anything, and changing your mind later is a mount-and-theme exercise rather than a content migration. The switching cost lives entirely in customization and in the deep links people have made into operation pages.

The scope of a renderer decision A renderer choice affects the mount, theming and deep links, while the OpenAPI document and the prose around it stay untouched. not committed the OpenAPI document guides and prose portable either way committed mount, theming, plugins operation deep links the real switching cost

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.

A useful way to close the decision is to write the three answers down and circulate them, rather than presenting a feature table. A table invites people to relitigate individual rows; three stated constraints and the conclusion they force is a decision somebody can disagree with specifically, which is a far shorter conversation. It also leaves a record that explains the choice to whoever revisits it in two years, by which point both tools will have changed and the reasoning will matter more than the comparison did.

One practical note on running the comparison itself: evaluate both against your own specification rather than a demo. The differences that matter in practice are almost never in the operations list, which both tools render well — they are in how a deeply nested schema displays, how a large enum reads, how a oneOf with a discriminator is presented, and how an unusual security scheme appears in the authorization panel. A demo specification exercises none of those, which is why a comparison based on demos so often produces a choice that feels wrong within a month of adopting it.

Whichever way the three constraints point, record the answer somewhere durable alongside the date. Renderers change, requirements change, and the next person to ask this question will be far better served by knowing what was true when the decision was taken than by re-reading a comparison of two products that have both moved on since.

A dated decision record is worth more than a comparison table, because it captures the constraints rather than the products.

Constraints age far more slowly than feature lists do, which is what makes them the durable part of the record.