Required dependencies

npm install @stoplight/elements @stoplight/elements-core
npm install @stoplight/http-spec @stoplight/json @stoplight/types
npm install react react-dom react-router-dom
npm install openapi3-ts swagger-schema-official lodash

No native build steps are required. These are pure JavaScript/TypeScript packages. If you use the web component distribution, no bundler is needed; load the UMD script from unpkg instead.

Project setup

1. Copy the source/ directory into your project, e.g. src/vendor/elements/.
2. Add path aliases in tsconfig.json so internal cross-package imports resolve correctly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@stoplight/elements-core": ["src/vendor/elements/elements-core/src/index.ts"],
      "@stoplight/elements": ["src/vendor/elements/elements/src/index.ts"]
    }
  }
}

3. If you use Webpack or Vite, mirror those aliases in your bundler config:

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@stoplight/elements-core': path.resolve(__dirname, 'src/vendor/elements/elements-core/src/index.ts'),
      '@stoplight/elements': path.resolve(__dirname, 'src/vendor/elements/elements/src/index.ts'),
    },
  },
});

4. Import the CSS where your application bootstraps:

import 'src/vendor/elements/elements-core/src/styles.css';
import 'src/vendor/elements/elements/src/styles.css';

5. No environment variables are required for basic usage. If you use the mock server feature, configure it through MockingProvider.

Public API

API

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

interface APIProps {
  apiDescriptionUrl?: string;
  apiDescriptionDocument?: string | object;
  basePath?: string;
  router?: 'history' | 'hash' | 'memory' | 'static';
  layout?: 'sidebar' | 'stacked' | 'responsive-sidebar';
  hideSchemas?: boolean;
  hideTryIt?: boolean;
  tryItCorsProxy?: string;
  tryItCredentialPolicy?: 'include' | 'omit' | 'same-origin';
  logo?: string;
}

declare function API(props: APIProps): JSX.Element;

The primary integration point. Pass either apiDescriptionUrl (a URL to a remote OAS document) or apiDescriptionDocument (an already-loaded object or YAML/JSON string). Choose layout based on your page structure: sidebar for three-column Stripe-style docs, stacked for single-column CMS integration.

transformOasToServiceNode

import { transformOasToServiceNode } from '@stoplight/elements';
import type { ServiceNode } from '@stoplight/elements';

function transformOasToServiceNode(apiDescriptionDocument: unknown): ServiceNode | null;

Converts a raw OpenAPI 2.0, 3.0, or 3.1 document object into the internal ServiceNode tree that Elements' rendering components consume. Returns null if the document is not a recognized OAS format. Use this when you need to pre-process or inspect the document tree before passing it to a layout component.

APIWithStackedLayout

import { APIWithStackedLayout } from '@stoplight/elements';

A layout-only variant of the API viewer that renders all operations stacked vertically, with no sidebar. Use this when embedding API docs into an existing page that already has its own navigation or when you want a simpler, single-column presentation inside a CMS.

Docs

import { Docs } from '@stoplight/elements-core';
import type { DocsProps } from '@stoplight/elements-core';

declare function Docs(props: DocsProps): JSX.Element;

Renders the documentation panel for a single parsed API node (operation, model, or service overview). Use Docs directly when you have already resolved the node and want to embed it in a custom layout without the full API container.

TableOfContents

import { TableOfContents } from '@stoplight/elements-core';

Renders the navigation tree for an API. Consumes an ITableOfContentsTree and emits selection events. Use when building a fully custom layout that manages its own sidebar.

Working examples

Scenario - Render a remote OpenAPI document as React component

A standard integration: render GitHub's public REST API using the sidebar layout inside a React application.

import React from 'react';
import { API } from '@stoplight/elements-core/../../../elements/src/index';
// or with alias: import { API } from '@stoplight/elements';
import '@stoplight/elements-core/src/styles.css';
import '@stoplight/elements/src/styles.css';

export function ApiDocs() {
  return (
    <API
      apiDescriptionUrl="https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.yaml"
      router="history"
      layout="sidebar"
    />
  );
}

Scenario - Load and transform an OAS document manually

Pre-load an OAS document, transform it to a service node for inspection, then render it stacked.

import React, { useEffect, useState } from 'react';
import { transformOasToServiceNode, APIWithStackedLayout } from '@stoplight/elements';
import type { ServiceNode } from '@stoplight/elements';

async function fetchSpec(url: string): Promise<unknown> {
  const res = await fetch(url);
  return res.json();
}

export function ManualDocs() {
  const [serviceNode, setServiceNode] = useState<ServiceNode | null>(null);

  useEffect(() => {
    fetchSpec('https://petstore3.swagger.io/api/v3/openapi.json').then(doc => {
      const node = transformOasToServiceNode(doc);
      console.log('operations count:', node?.children?.length ?? 0);
      setServiceNode(node);
    });
  }, []);

  if (!serviceNode) return <p>Loading...</p>;

  return <APIWithStackedLayout serviceNode={serviceNode} />;
}

Scenario - Web Component in plain HTML (no bundler)

Embed Elements in a static HTML page without any build tooling.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>API Docs</title>
    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css" />
  </head>
  <body>
    <elements-api
      apiDescriptionUrl="https://petstore3.swagger.io/api/v3/openapi.json"
      router="hash"
      layout="sidebar"
    ></elements-api>
  </body>
</html>

Scenario - Embedding Docs for a single operation in a custom layout

Use the lower-level Docs component from elements-core to render one operation's docs inside your own shell.

import React from 'react';
import { Docs, InlineRefResolverProvider } from '@stoplight/elements-core';
import { transformOasToServiceNode } from '@stoplight/elements';
import petstore from './petstore.json'; // local OAS document

const serviceNode = transformOasToServiceNode(petstore);
const firstOperation = serviceNode?.children?.[0];

export function SingleOperationDoc() {
  if (!firstOperation) return null;
  return (
    <InlineRefResolverProvider document={petstore}>
      <Docs nodeType={firstOperation.type} nodeData={firstOperation.data} />
    </InlineRefResolverProvider>
  );
}

File walkthrough

• elements/ - The publishable @stoplight/elements package. Entry point is elements/src/index.ts, which re-exports API, APIWithStackedLayout, transformOasToServiceNode, useExportDocumentProps, and ServiceNode.
• elements/src/containers/API.tsx - The top-level API container; wires together routing, data fetching, layout selection, and the OAS transform pipeline.
• elements/src/components/API/ - Three concrete layout components (APIWithSidebarLayout, APIWithStackedLayout, APIWithResponsiveSidebarLayout) consumed by the container.
• elements/src/utils/oas/ - OAS-to-service-node transformation: index.ts dispatches on OAS version, oas2.ts / oas3.ts provide format-specific source maps.
• elements/src/web-components/ - Registers the <elements-api> custom element via window.customElements.define.
• elements/src/hooks/useExportDocumentProps.tsx - Hook that computes props (href, filename) for an export/download button.
• elements-core/ - The @stoplight/elements-core package. All foundational components, hooks, HOCs, and context live here.
• elements-core/src/components/Docs/ - Docs and ParsedDocs components for rendering operations, models, and service overviews.
• elements-core/src/components/TryIt/ - Interactive API console component and TryItWithRequestSamples combo.
• elements-core/src/components/TableOfContents/ - Navigation tree component, types, and findFirstNode utility.
• elements-core/src/components/MarkdownViewer/ - Markdown renderer with pluggable custom components.
• elements-core/src/context/ - Providers for routing type, mocking, options, persistence, and inline ref resolution.
• elements-core/src/hoc/ - withRouter, withMosaicProvider, withQueryClientProvider HOCs for wrapping custom components.
• elements-core/src/hooks/ - Data hooks: useParsedData, useParsedValue, useBundleRefsIntoDocument, useRouter, useResponsiveLayout.
• elements-core/src/utils/ - Guards (isHttpOperation, isHttpService), URL helpers (resolveUrl), slugification, and ref-resolving infrastructure.
• elements-dev-portal/ - Dev portal package for multi-API navigation; extends the core layout with project/branch/API selection.

Common pitfalls and fixes

• Peer dep version mismatch for React: Elements requires React 17+. If you see hooks-related runtime errors, ensure react and react-dom are the same version across your project with npm ls react.
• CSS not loading: The component tree renders unstyled if you omit the CSS imports. Import both elements-core/src/styles.css and elements/src/styles.css at your app root.
• window.customElements is undefined in SSR: The web component entry (elements/src/web-components/index.ts) calls window.customElements.define at module evaluation time. Guard it with if (typeof window !== 'undefined') or exclude it from your SSR bundle.
• OAS 3.1 JSON Schema dialect: transformOasToServiceNode forcibly sets jsonSchemaDialect to draft-07 for OAS 3.1 documents. If your document relies on draft-2020-12 features they will not validate correctly.
• Path alias conflicts: If your project already imports @stoplight/elements from npm, the tsconfig alias will shadow it. Remove the npm package first or use a distinct alias name.
• transformOasToServiceNode returns null: The function returns null for any document that lacks a top-level swagger or openapi field. Ensure your document is fully dereferenced and parsed from JSON/YAML before passing it in.

Vibe-coding prompt template

I have a local copy of the Stoplight Elements source in `source/` (packages: elements, elements-core, elements-dev-portal).
I also have a USAGE.md file in the same directory that documents all real exports and integration steps.

My project is a [React / Next.js / Vite / Express + React] TypeScript application.

Please do the following step by step:

1. Read USAGE.md and source/elements/src/index.ts to understand the available exports.
2. Set up tsconfig.json path aliases so `@stoplight/elements` and `@stoplight/elements-core` resolve from `source/`.
3. Install all required npm dependencies listed in USAGE.md § "Required dependencies".
4. Create a component at `src/components/ApiDocs.tsx` that:
   - Imports `API` from `@stoplight/elements`
   - Accepts a prop `specUrl: string`
   - Renders the API component with `router="history"` and `layout="sidebar"`
5. Import the required CSS files in `src/main.tsx` (or `_app.tsx` for Next.js).
6. If the project does SSR, guard any web-component imports so they only run client-side.
7. Show me the final diff of every file changed.

Upstream package: @stoplight/elements (stoplightio_elements).
Source directory: source/
Integration reference: USAGE.md

License and credit

The source is licensed under the Apache 2.0 license; see source/elements/LICENSE and source/elements-core/LICENSE for the full text. Upstream project: Stoplight Elements, published as @stoplight/elements and @stoplight/elements-core on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.