Web Component

@apiboost/omnispec ships a framework-agnostic Web Component (<omnispec-renderer>) alongside the React component. It is part of the free package — no additional install. Use it from vanilla HTML, Vue, Angular, Svelte, or any other framework that can render a DOM element.

Quick start

The fastest path is the standalone bundle — a single self-contained <script> that ships React, ReactDOM, and the renderer inline, with no build step on the consumer side.

<!doctype html>
<html>
  <body>
    <script src="https://unpkg.com/@apiboost/omnispec@latest/dist/wc/standalone.js"></script>
    <omnispec-renderer
      spec-url="https://petstore3.swagger.io/api/v3/openapi.json"
    ></omnispec-renderer>
  </body>
</html>

For framework apps, prefer the subpath import so React/ReactDOM are shared with your existing tree:

import '@apiboost/omnispec/wc'
// <omnispec-renderer> is now registered globally.

Two configuration paths

Declarative HTML attributes

Best for scalar config like URLs, enums, and booleans:

<omnispec-renderer
  spec-url="https://example.com/openapi.json"
  theme-base="auto"
  display-mode="compact"
  navigation-mode="grouped"
  allow-try-it="true"
  proxy-url="/api/proxy"
></omnispec-renderer>

Imperative property assignment

Recommended for complex objects (parsed specs, theme overrides, sidebar nav):

import type { OmniSpecRendererElement } from '@apiboost/omnispec/wc'

const el = document.querySelector('omnispec-renderer') as OmniSpecRendererElement
el.spec = parsedSpecObject
el.theme = {
  base: 'dark',
  overrides: { '--omnispec-color-primary': '#8B5CF6' },
}
el.sidebarNav = {
  items: [
    { id: 'home', label: 'Home', href: '/' },
  ],
}

You can also stringify-then-set the same complex props as JSON attributes — the element parses them with a try/catch and logs a console error on failure:

<omnispec-renderer
  spec-url="/openapi.json"
  theme='{"base":"dark"}'
></omnispec-renderer>

The imperative property always wins over an attribute when both are set.

Attribute reference

Attribute	Type	Description
`spec-url`	string	URL to fetch the spec from.
`spec`	JSON string	Inline spec content (object or string) — see properties.
`theme-base`	`'light' \| 'dark' \| 'auto'`	Theme base. `'auto'` follows the system preference.
`theme-toggle`	boolean	Show the floating theme toggle in `'auto'` mode. Defaults to `true`.
`theme`	JSON string	Full `ThemeConfig` (use the property in JS).
`sidebar-nav`	JSON string	Sidebar nav config (use the property in JS).
`display-mode`	`'compact' \| 'reference'`	Layout mode.
`navigation-mode`	`'grouped' \| 'segmented'`	Nav grouping.
`layout`	`'sidebar' \| 'stacked'`	Page layout.
`sidebar-position`	`'left' \| 'right'`	Sidebar placement.
`try-it-layout`	`'inline' \| 'panel'`	Try-It position in compact mode (default `panel`). `panel` = sticky right column; `inline` = collapsed below the operation. Ignored in reference mode.
`schema-style`	`'lines' \| 'tokens' \| 'chain' \| 'table' \| 'card'`	Schema tree style. `table` and `card` require Pro.
`allow-try-it`	boolean	Enable Try-It.
`interactive-oauth`	boolean	Opt out of the Pro interactive OAuth flow with `"false"` (forces manual token paste). No effect without Pro.
`default-expand-operations`	boolean	Expand every operation on load.
`proxy-url`	string	Try-It proxy endpoint.
`server-url`	string	Override the API base URL for Try-It, ignoring the spec's `servers`.
`try-it-persist-ttl`	number (ms)	How long to persist Try-It auth and inputs in the browser.
`download-link`	boolean or URL	Show a download button — pass `true` to use the spec URL or a string to specify a different URL.
`docs-url`	string	URL for the upgrade prompt's docs link.
`upgrade-url`	string	URL for the upgrade prompt's upgrade link.

Boolean attributes are truthy by default: any value other than 'false', '0', or 'off' (case-insensitive) — including a bare attribute with no value — is treated as true. To disable a boolean, set it to false/0/off or leave the attribute unset.

Property reference

For complex/JSON config, use the property API. Properties are available on the custom element after it has been created.

Property	Type	Description
`spec`	`string \| object`	URL, raw string, or parsed spec object.
`theme`	`ThemeConfig`	Full theme config including `overrides`, `onThemeChange`.
`sidebarNav`	`SidebarNavConfig`	Custom sidebar navigation.

Events

The element dispatches standard CustomEvents that bubble and are composed through the shadow boundary. The detail property carries the typed payload.

Event	`detail` type	When
`spec-loaded`	`SpecLoadedInfo` (`{ title, version, type }`)	After the spec has been fetched and parsed.
`try-it-request`	`TryItRequest`	When the user clicks "Try it" — payload of the outgoing request.
`try-it-response`	`TryItResponse`	When the Try-It response is received.

el.addEventListener('spec-loaded', (e) => {
  console.log((e as CustomEvent).detail) // { title, version, type }
})

Shadow DOM

The element uses open shadow DOM. You can inspect it via el.shadowRoot for debugging. The renderer's styles are isolated from your page — host page CSS does not leak in, and renderer styles do not leak out.

Design tokens cascade in

CSS custom properties inherit through shadow boundaries, so design tokens defined on the host element are picked up by the renderer:

omnispec-renderer {
  --omnispec-color-primary: #8B5CF6;
  --omnispec-color-primary-hover: #7C3AED;
  --omnispec-font-sans: 'Inter', sans-serif;
}

See Theming for the full token list.

Sizing the element

By default the element renders as display: block with width: 100% and height: 100%. Position it within your layout like any other block-level element:

omnispec-renderer {
  height: 100vh;
}

Framework integration

Vanilla HTML

<script src="https://unpkg.com/@apiboost/omnispec@latest/dist/wc/standalone.js"></script>
<omnispec-renderer spec-url="/openapi.json"></omnispec-renderer>

Vue 3

Tell the Vue compiler that any <omnispec-...> tag is a custom element so it does not try to resolve it as a Vue component:

// vite.config.ts
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue({
    template: {
      compilerOptions: {
        isCustomElement: (tag) => tag.startsWith('omnispec-'),
      },
    },
  })],
})

<script setup lang="ts">
  import '@apiboost/omnispec/wc'
  import { ref, onMounted } from 'vue'
  import type { OmniSpecRendererElement } from '@apiboost/omnispec/wc'

  const docs = ref<OmniSpecRendererElement | null>(null)
  onMounted(() => {
    if (docs.value) docs.value.theme = { base: 'dark' }
  })
</script>

<template>
  <omnispec-renderer
    ref="docs"
    spec-url="/openapi.json"
    @spec-loaded="console.log($event.detail)"
  ></omnispec-renderer>
</template>

Angular

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
import '@apiboost/omnispec/wc'

@Component({
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<omnispec-renderer spec-url="/openapi.json"></omnispec-renderer>`,
})
export class AppComponent {}

Svelte 5

<script lang="ts">
  import '@apiboost/omnispec/wc'
  import type { OmniSpecRendererElement } from '@apiboost/omnispec/wc'

  let docs: OmniSpecRendererElement | undefined = $state()
  $effect(() => {
    if (docs) docs.theme = { base: 'dark' }
  })
</script>

<omnispec-renderer
  bind:this={docs}
  spec-url="/openapi.json"
></omnispec-renderer>

React

If you already use React, prefer the React component — there is no benefit to wrapping it in a custom element. The <omnispec-renderer> element exists for non-React stacks.

Pro features in the Web Component

Pro

Pro renderers (GraphQL, SOAP/WSDL, gRPC), full white-label theming (theme.overrides), and interactive OAuth require Apiboost OmniSpec Pro. In the free core, the <omnispec-renderer> element renders OpenAPI and AsyncAPI specs with the base light/dark/auto theme and CSS-variable overrides. A parallel Pro Web Component is not shipped today — Pro features are available through the React component.

Limitations and future work

JSON attributes are convenient but verbose. Prefer the imperative property API for production use.
@emotion/css style mirroring copies emotion-generated styles from document.head into the shadow root. The footprint per page is tiny (typically a few kilobytes), but if you mount many <omnispec-renderer> elements on one page they will each carry a copy. For most users this is not a concern.

Quick start​

Two configuration paths​

Declarative HTML attributes​

Imperative property assignment​

Attribute reference​

Property reference​

Events​

Shadow DOM​

Design tokens cascade in​

Sizing the element​

Framework integration​

Vanilla HTML​

Vue 3​

Angular​

Svelte 5​

React​

Pro features in the Web Component​

Limitations and future work​