API Viewer Element

1.0.0-pre.10 verified Sat Apr 25 auth: no javascript

Web component that generates interactive API documentation and live playgrounds for custom elements / web components. It parses custom-elements.json manifest and renders property, attribute, method, event, and slot documentation alongside a live demo editor. Version 1.0.0-pre.10 is the latest pre-release, with patches updating demo copy button styles. Key differentiator: fully custom-element-based, works in any framework or vanilla HTML, built on LitElement. Alternatives like Storybook or Docz typically require framework-specific integrations. Ships TypeScript types (from @open-wc). Part of Open Web Components ecosystem.

Common errors

error Error: Failed to load manifest: ... ↓

cause The manifest URL is incorrect or CORS issues.

fix

Ensure the manifest URL is valid and the server allows CORS. For local testing, use a local server or inline the manifest.

error Uncaught TypeError: Cannot read properties of undefined (reading 'map') ↓

cause The manifest property is undefined or malformed.

fix

Check that the manifest is properly parsed JSON and contains the expected structure (e.g., tags array).

error api-viewer does not appear to be defined ↓

cause The web component is not registered.

fix

Ensure you have imported 'api-viewer-element' before using the <api-viewer> tag.

Warnings

gotcha The component requires a valid custom-elements.json manifest. Without it, nothing renders. ↓

fix Generate a manifest using @custom-elements/manifest or similar tool.

gotcha The manifest must be set as a JavaScript object, not a string. Passing a URL string will not work. ↓

fix Fetch the JSON and assign the parsed object to the `manifest` property.

breaking Version 1.0.0-pre.10 is a pre-release; breaking changes may occur before stable. There is no stable release yet. ↓

fix Pin to a specific pre-release version and test updates carefully.

Install

npm install api-viewer-element

yarn add api-viewer-element

pnpm add api-viewer-element

Imports

ApiViewer
wrong
```
default or named import
```
correct
```
import 'api-viewer-element'
```
Importing the module registers the custom element globally; no need to import a class.
ApiViewer (as a constructor)
wrong
```
import { ApiViewer } from 'api-viewer-element'
```
correct
```
import 'api-viewer-element'; const viewer = document.querySelector('api-viewer')
```
The element is registered as a custom element via side effect. To access the class, use `customElements.get('api-viewer')`.
loader
```
import { loader } from 'api-viewer-element'; loader().then(() => ...)
```
The `loader` function returns a Promise that resolves when the component is ready. Useful for conditional loading or ensuring the element is defined.

Quickstart

Shows how to use the <api-viewer> element: import the web component, fetch a custom-elements.json manifest, and set it as a property. The component renders documentation and a live demo.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>API Viewer Example</title>
  <script type="module">
    import 'api-viewer-element';
    // fetch custom-elements.json from a URL or inline
    const manifestUrl = 'https://unpkg.com/@open-wc/api-viewer-element/custom-elements.json';
    fetch(manifestUrl)
      .then(res => res.json())
      .then(manifest => {
        document.querySelector('api-viewer').manifest = manifest;
      });
  </script>
</head>
<body>
  <api-viewer style="width: 100%; height: 100vh;"></api-viewer>
</body>
</html>