Stoplight Elements: Embeddable API Reference Docs from OpenAPI and Markdown

What Stoplight Elements actually renders

Elements is a front end for API descriptions that already exist. You give it a URL pointing at an OpenAPI document, and it produces a documentation page with a reference section, code samples, examples and a Try It console. The README frames the output as either a three-column layout it calls Stripe-esque or a stacked layout that fits into a CMS that has its own navigation.

The intended audience is narrow. This is for teams that treat the OpenAPI file as the source of truth and want a viewer, not for teams looking for a writing tool. The repository topics list OpenAPI v2.0, v3.0 and v3.1 support, so a spec written against any of those versions is in scope. Markdown articles sit alongside the reference, which is what makes the stacked layout plausible for a documentation site that mixes conceptual pages with endpoint listings.

The boundary matters. Elements does not host anything, does not store your spec, and does not give you an editor. The README points at Stoplight Studio and the Stoplight Platform for those jobs, which tells you where the open source project stops.

React components versus Web Components: the two distribution paths

The same rendering engine ships twice. As a React package it is imported and mounted inside a React tree, which means your router, your bundler and your build pipeline all apply. As a Web Component it is loaded from a script tag and used as a custom element, which means it works in an Angular app or a single static HTML file with no React dependency at all.

The repository layout backs this up. The examples directory contains react-cra, angular and bootstrap projects, and the README describes the bootstrap example as a single HTML page using the Web Components distribution through a global script tag. That example is the one case where the README says to skip the install step and open the HTML file directly.

The trade-off is real. The Web Component path pulls a compiled bundle and a stylesheet from a CDN, so you inherit whatever version that URL resolves to unless you pin it yourself. The React path gives you version control through your package manager but drags React into the dependency graph. Neither path gives you server-side rendering of the documentation content out of the box, because the components fetch the description at runtime in the browser.

Installing Elements and rendering a first spec

The README gives the npm install command for the React package. Run it in the project where the documentation will live.

$ npm install @stoplight/elements

Then import the API component and point it at a description URL. The README uses the GitHub REST API spec as its example, and sets router to history.

import { API } from "@stoplight/elements";

<API
  apiDescriptionUrl="https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.yaml"
  router="history"
/>

If you are not using React, the README gives a Web Component page instead. It loads the bundle and the stylesheet from unpkg, then places an elements-api element with router set to hash and layout set to sidebar.

<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">

<elements-api
  apiDescriptionUrl="https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.yaml"
  router="hash"
  layout="sidebar"
/>

According to the README, loading that page in a browser should show the GitHub REST API documented in Stoplight Elements. The repository also ships example projects under examples, including react-cra, angular and bootstrap; the README says to clone the repo, open one of those directories, run yarn to install dependencies and yarn start to run it.

The Try It console and what it implies about your spec

The roadmap lists API Console, also called Try It, as a completed item, alongside automatic code samples and automatic examples. In practice this means the rendered page includes a request builder derived from the operation definition in your spec. The README credits httpsnippet for code sample generation and openapi-sampler for example generation, so the samples you see are generated from the schema rather than hand-written.

That has a consequence worth stating plainly. If your spec has thin or wrong schemas, the generated examples and samples will be thin or wrong too. Elements does not invent missing information. A parameter without a description renders without a description. A response without an example schema renders without a meaningful sample. The quality of the output is bounded by the quality of the input document, and there is no editorial layer between the two.

The Try It console also implies browser-side requests to your API. The README does not document a proxy or a server-side relay, so cross-origin configuration on the API itself is the reader's problem, not something the components solve.

Where Elements is the wrong tool

Elements is a rendering library, and that is the whole of it. If you need versioned documentation with a review workflow, role-based publishing, or search that spans several products, none of that is in the README. The roadmap mentions multiple APIs under the label Dev Portal, which suggests a single deployment can present more than one description, but that is a long way from a documentation platform with editorial controls.

The other limitation is the release cadence visible in the repository. The most recent release listed is v6.1.10 from 2021-02-09, with v5.2.7 and v5.2.6 before it. The last push to the default branch was on 2026-09-24, so the codebase is being touched, but the published release tags do not reflect that activity. Anyone pinning to a tagged release should check what the tag actually contains rather than assuming it matches the current main branch.

Analytics deserve a mention here too. The README states that Elements uses Scarf to collect anonymized installation analytics and that these run only during installation. That is a build-time network call in your CI, and some organisations will not accept it silently. The README documents two opt-outs.

Opting out of Scarf analytics

The README gives two mechanisms. The first is a field in your project's package.json, shown in the README as a JSON fragment with a comment. The second is an environment variable applied to the install command.

{
  "scarfSettings": {
    "enabled": false
  }
}

The README also gives the environment variable form, which applies to the environment that installs your npm packages rather than to a single project file.

SCARF_ANALYTICS=false npm install

How Elements compares with rendering the spec yourself

The obvious alternative is to take the OpenAPI document and render it with a general-purpose toolchain rather than a purpose-built component. A static site generator plus a schema renderer gives you full control over layout, routing and build output, and it keeps the documentation inside the same pipeline as the rest of your site. The difference in approach is where the work sits: with Elements you configure a component and accept its layout decisions, while with a hand-rolled renderer you write the presentation layer and own it.

Elements is the better fit when the reference documentation is one page among many and you want it working this week. The hand-rolled route is the better fit when the documentation is the product and the layout has to match a design system exactly. There is also the question of the Try It console: reproducing a request builder with generated code samples is a substantial amount of work, and that is the piece Elements gives you that a plain schema renderer does not.

A third option is a hosted documentation service. That trades the Apache-2.0 licence and self-hosting for a managed product with authoring tools. The README's own Integrations section points at the Stoplight Platform for exactly that, which is an honest signal about where the open source boundary sits.

Licence, maintenance and upgrade cost

Elements is licensed under Apache-2.0 according to the repository's package.json and the LICENSE.md file at the top level. That permits commercial use and modification, and it includes a patent grant. It does not give you any warranty, and the repository's author field points at Stoplight support rather than a foundation. If you fork it, you carry the maintenance yourself.

The upgrade cost is the part to think about before adopting. The repository is a Lerna monorepo with a packages directory, a demo workspace and a yarn.lock at the root, so a fork inherits a multi-package build rather than a single library. The devDependency list is long and includes Storybook 7.5.3, Cypress 13, Jest 26 and ESLint 7, which are not all on the same generation of tooling. Rebuilding this from source is a project, not an afternoon.

For consumers the cost is lower. Installing the published package and passing an apiDescriptionUrl means your upgrade path is a version bump and a check that your spec still renders. The risk sits with the gap between the last tagged release and the current branch, which is the thing to verify before you pin.

Editorial conclusion

Adopt Elements if you already maintain an OpenAPI description and want a reference UI you can drop into an existing React app or a plain HTML page without running a documentation server. Do not adopt it if you need a hosted portal with authoring, review workflow or search across many products, because Elements is the rendering layer and nothing else. Before committing, verify that your spec parses cleanly through the version you install, confirm whether the Scarf analytics opt-out in package.json is acceptable in your build environment, and check the release history on the repository against the version you plan to pin.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. stoplightio/elements on GitHub