Stoplight Elements is an open-source set of web components that renders an OpenAPI document into a three-column interactive API reference. You drop it into an HTML page or a React app, point it at a spec, and you get docs that look like Stripe's or Spotify's, plus a working "Try It" console. No build step. No backend. Just a script tag or an npm install.
This guide walks through what Stoplight Elements actually does, how to install it three different ways, how to customize the layout, and when it's the right pick versus Redoc, Swagger UI, or Scalar. It also covers the elephant in the room: Stoplight was acquired by SmartBear in August 2023, and most of the Elements codebase has been on a slow drip of dependency bumps since.
What is Stoplight Elements?
Stoplight Elements is a free, open-source library of React components and web components, MIT-licensed, that takes an OpenAPI 2 or 3.x file and renders it as a browsable API reference. The project lives at github.com/stoplightio/elements (around 2.4k stars) and ships on npm as @stoplight/elements. The current version is 9.0.19, published April 2026.
The core idea is "drop-in docs." You don't need a static site generator, a backend, or a build pipeline. You can paste a <script> tag into a plain HTML file, pass it your OpenAPI URL, and ship a working API reference. Spotify uses Elements for parts of its Web API docs. Dyte uses it for its video SDK reference. Authmoji uses it for its developer portal. If you've browsed a docs site with a left sidebar of endpoints, a middle column of descriptions, and a right-hand "Try It" panel, you've probably seen Elements or one of its clones.
Three packages matter:
@stoplight/elements: the core component for embedding a single OpenAPI reference@stoplight/elements-dev-portal: adds multi-API navigation and a developer-portal style layout@stoplight/elements-core: shared primitives, rarely installed directly
Most projects only need the first one.
How to install Stoplight Elements
There are three install paths. Pick the one that matches your stack.
1. CDN drop-in (no build step)
This is the fastest path. Add two lines to your HTML page:
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css" />
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
</head>
<body>
<elements-api
apiDescriptionUrl="https://raw.githubusercontent.com/stoplightio/Public-APIs/master/reference/zoom/api.json"
router="hash"
layout="sidebar"
/>
</body>
</html>
Open that file in a browser and you'll see an interactive reference. The apiDescriptionUrl attribute is the only required prop. Everything else has a sensible default.
This path works great for static hosting (S3, GitHub Pages, Netlify, Vercel) and for embedding into a CMS like WordPress where you can't add a build step.
2. React app (npm install)
If you have a React project, install the package:
npm install @stoplight/elements
Then use the component:
import "@stoplight/elements/styles.min.css";
import { API } from "@stoplight/elements";
function ApiDocs() {
return (
<API
apiDescriptionUrl="https://docs.example.com/openapi.yaml"
router="hash"
layout="sidebar"
/>
);
}
The React component supports the same props as the web component, just in camelCase. For Next.js, import the component with dynamic and ssr: false, because Elements relies on browser APIs.
3. Self-hosted assets
If you don't want a CDN dependency, copy the built JS and CSS into your own static assets:
npm install @stoplight/elements
cp node_modules/@stoplight/elements/web-components.min.js ./public/
cp node_modules/@stoplight/elements/styles.min.css ./public/
Then reference your own paths in the HTML. This is the path you want for offline docs, air-gapped environments, or sites with strict CSP rules that block third-party scripts.
Stoplight Elements layout and routing
Two props shape the whole experience: layout and router.
layout can be:
sidebar: the default three-column view with a left endpoint list. Best for medium-to-large APIs.stacked: a single flowing column with everything inline. Best for tiny APIs (under ten endpoints) or when you want to embed the reference inside a longer guide.responsive: switches between the two based on viewport width.
router controls how URLs work:
hash: uses#/paths/...fragments. Works on any static host with zero server config. Picked by default.history: uses real paths like/paths/.... Cleaner URLs, but you have to configure your server to sendindex.htmlfor unknown routes.memory: keeps state in JavaScript, no URL changes. Use this when embedding inside another app that owns routing.static: pre-renders a path and freezes it. Use it when the docs live inside a larger SPA.
For an embedded reference inside an existing developer portal, memory with stacked gives you a single inline block that doesn't fight your host page for routing.
Customizing Stoplight Elements
Customization is the area where Elements is weakest, and it's the most common complaint in the Stoplight community forum. There's no theming API. You override styles with plain CSS by targeting the rendered class names.
The supported levers are:
<elements-api
apiDescriptionUrl="/openapi.yaml"
layout="sidebar"
router="hash"
hideTryIt="false"
hideExport="false"
hideSchemas="false"
hideInternal="true"
tryItCredentialsPolicy="omit"
tryItCorsProxy="https://cors-proxy.example.com"
/>
The interesting ones:
hideInternal: drops any operation or model taggedinternal: truein the OpenAPI spec. This lets you keep one spec file and surface different views to internal vs external audiences.tryItCorsProxy: routes "Try It" requests through a proxy. You'll need this whenever the target API doesn't return permissive CORS headers, which is most of them.hideTryIt: kills the interactive console. Useful if you only want a static reference (closer to Redoc behavior).
For deeper visual changes, you write CSS overrides:
.sl-elements-api {
--color-primary: #6366f1;
font-family: "Inter", sans-serif;
}
.sl-elements-api .HttpOperation__path {
font-weight: 600;
}
There's no documented list of stable class names, so anything beyond CSS variables is technically fragile across version bumps. In practice the markup hasn't shifted much since version 7, so most overrides survive upgrades.
Stoplight Elements vs Redoc, Swagger UI, and Scalar
This is the comparison every team makes before installing. Here's the honest read.
| Feature | Stoplight Elements | Redoc | Swagger UI | Scalar |
|---|---|---|---|---|
| Open source | Yes (MIT) | Yes (MIT) | Yes (Apache 2.0) | Yes (MIT) |
| OpenAPI 3.1 | Yes | Yes (since v2.2) | Yes | Yes |
| Interactive "Try It" | Yes | Paid (Redocly) | Yes | Yes |
| Markdown articles alongside reference | Yes | No | No | Limited |
| Three-column layout | Yes | Yes | No | Yes |
| AsyncAPI support | No | No | No | No |
| Active development (2026) | Maintenance mode | Active | Active | Very active |
| Bundle size (gzipped) | ~340 KB | ~280 KB | ~410 KB | ~250 KB |
The shorter version:
- Pick Stoplight Elements if you want a free three-column reference with a built-in "Try It" console and you're comfortable that releases are slow.
- Pick Redoc if you want the cleanest read-only reference and you don't need the request console. The "Try It" feature is paywalled behind Redocly Reference.
- Pick Swagger UI if you live inside an existing Swagger toolchain (Swagger Editor, SwaggerHub) and want zero surprises. The layout looks dated next to the other three.
- Pick Scalar if you want the newest take with the most active development, the cleanest defaults, and the best out-of-the-box theming.
For brand-new projects in 2026, Scalar is the one most teams I talk to are picking. Stoplight Elements is the safe choice if you already have it in production or you specifically want the markdown-articles-alongside-reference behavior.
When Stoplight Elements is the right pick
Use it when:
- You already have a well-maintained OpenAPI file and just need to render it
- You want one spec to power both internal and external docs via
hideInternal - You need to embed an API reference inside a CMS or developer portal where you control the chrome
- You like Spotlight-flavored Markdown for descriptions (tabs, callouts, embedded JSON examples)
When to skip Stoplight Elements
Skip it when:
- You don't have an OpenAPI file yet. Elements is a renderer, not a generator. You still have to write or generate the spec.
- You want a full docs site with guides, tutorials, changelogs, and a homepage. Elements gives you the reference, not the surrounding site. You'd pair it with Docusaurus, Starlight, or Fumadocs.
- You need active development. SmartBear's investment in Elements since the 2023 acquisition has been mostly dependency upgrades. Releases ship, but new features are rare.
- You want server-rendered docs that crawl well. Elements is client-side JavaScript, so Google sees a near-empty page until the JS executes. This hurts ranking for product pages where SEO matters.
- You're not a developer. Elements assumes you can write HTML and run an npm install. If your team is product, marketing, or support, a hosted tool is a faster path.
That last point matters. Stoplight Elements is great if you're already maintaining an OpenAPI spec and you have a developer to wire it up. If you don't have a spec, or you want a full hosted docs site with guides plus API reference plus a homepage, AI-generated tools like Docsio skip the OpenAPI build entirely and generate the whole site from your existing API or product URL.
Common Stoplight Elements problems and fixes
A few issues come up over and over in the issue tracker:
CORS errors in "Try It". The target API needs Access-Control-Allow-Origin set, or you have to route requests through tryItCorsProxy. Stoplight does not host a public proxy. You'll spin up your own, or use a self-hosted one like Bump's open-source cors-toujours.
Refs not resolving. Elements does resolve $ref URLs, but it does so in the browser, which is slow on large specs and fails on auth-protected refs. If you have a multi-file spec, bundle it server-side with redocly bundle or swagger-cli bundle and serve a single file.
hideTryItPanel hides code samples too. There's a separate prop, hideTryIt, that hides the panel but keeps generated code samples visible. Use that instead.
Slow first paint on big specs. Elements parses the entire OpenAPI document on load. For specs over ~5 MB, consider splitting into multiple smaller APIs and using elements-dev-portal to navigate between them.
Search doesn't work. Elements has no built-in search bar. The dev-portal package adds one, but only across the API tree, not into descriptions. For full-text search you have to wrap Elements in your own host page with something like Algolia DocSearch.
Stoplight Elements pricing
Elements itself is free and open source under the MIT license. There's no usage cap, no telemetry, and no signup required. You can host it anywhere.
The paid Stoplight Platform (the design tool and hosted developer portal) is separate. Pricing for Stoplight Platform is not public; SmartBear sales handles it. Most teams using Elements never touch the paid platform. The two are decoupled by design.
FAQ
Is Stoplight Elements still maintained?
Yes, but slowly. Stoplight was acquired by SmartBear in August 2023, and since then the Elements repository has shipped mostly dependency bumps and minor fixes rather than new features. The most recent release as of writing is 9.0.19 from April 2026. It works fine, it's not abandoned, but new functionality is rare.
Can Stoplight Elements work with OpenAPI 3.1?
Yes. Elements supports OpenAPI 2.0, 3.0, and 3.1, which was the original differentiator versus Swagger UI before Swagger UI also added 3.1 support. JSON Schema and webhooks are both rendered correctly.
Does Stoplight Elements support AsyncAPI?
No. Elements is OpenAPI-only. For AsyncAPI you'd use the AsyncAPI Generator React template or a paid tool like Bump.sh. See our AsyncAPI guide for the full picture.
Is Stoplight Elements better than Swagger UI?
For most use cases, yes. Elements has a more modern three-column layout, supports Markdown articles alongside the reference, and renders cleaner by default. Swagger UI is still the right pick if you already use SwaggerHub or want the most familiar layout for developers used to OpenAPI tooling.
How do I add custom CSS to Stoplight Elements?
Load your CSS after the Elements stylesheet and override the documented CSS variables (like --color-primary) or target the .sl-elements-api class scope. Avoid styling deeper internals, since class names below the top level can change between major versions.
The bottom line on Stoplight Elements
If you maintain an OpenAPI spec and want a free, drop-in renderer with a working "Try It" console, Stoplight Elements is a solid choice. The maintenance pace is slow but the code is stable, and the three-column layout is what most users expect from a modern API reference.
If you don't yet have an OpenAPI spec, or you want a full docs site rather than a reference embed, Elements is the wrong starting point. You'd be building a spec just to render it, when an AI-driven API documentation tool can generate the whole site from your code or URL.
Want a hosted docs site that includes API reference plus guides, changelogs, and a homepage, generated from your existing site in minutes? Try Docsio free. One URL in, branded docs site out.