README.md

Storybook Docs for Web Components

• Installation
• Props tables
• Stories not inline
• More resources

Installation

• Be sure to check the installation section of the general addon-docs page before proceeding.

• Be sure to have a custom-elements.json file.

• Add to your .storybook/preview.js

  import { setCustomElementsManifest } from '@storybook/web-components';
  import customElements from '../custom-elements.json';
  
  setCustomElementsManifest(customElements);

• Add to your story files

  export default {
    title: 'Demo Card',
    component: 'your-component-name', // which is also found in the `custom-elements.json`
  };

Props tables

In order to get Props tables documentation for web-components you will need to have a custom-elements.json file.

You can hand write it or better generate it. Depending on the web components sugar you are choosing your milage may vary.

Known analyzers that output custom-elements.json v1.0.0:

• @custom-elements-manifest/analyzer
  • Supports Vanilla, LitElement, FASTElement, Stencil, Catalyst, Atomico

Known analyzers that output older versions of custom-elements.json:

• web-component-analyzer
  • Supports LitElement, Polymer, Vanilla, (Stencil)
• stenciljs
  • Supports Stencil (but does not have all metadata)

To generate this file with Stencil, add docs-vscode to outputTargets in stencil.config.ts:

{
  type: 'docs-vscode',
  file: 'custom-elements.json'
},

The file looks something like this:

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/my-element.js",
      "declarations": [
        {
          "kind": "class",
          "description": "",
          "name": "MyElement",
          "members": [
            {
              "kind": "field",
              "name": "disabled"
            },
            {
              "kind": "method",
              "name": "fire"
            }
          ],
          "events": [
            {
              "name": "disabled-changed",
              "type": {
                "text": "Event"
              }
            }
          ],
          "superclass": {
            "name": "HTMLElement"
          },
          "tagName": "my-element"
        }
      ],
      "exports": [
        {
          "kind": "custom-element-definition",
          "name": "my-element",
          "declaration": {
            "name": "MyElement",
            "module": "src/my-element.js"
          }
        }
      ]
    }
  ]
}

For a full example see the web-components-kitchen-sink/custom-elements.json.

Stories not inline

By default stories are rendered inline. For web components that is usually fine as they are style encapsulated via shadow dom. However when you have a style tag in you template it might be best to show them in an iframe.

To always use iframes you can set

addParameters({
  docs: {
    inlineStories: false,
  },
});

or add it to individual stories.

<Story inline={false} />

More resources

Want to learn more? Here are some more articles on Storybook Docs:

• References: DocsPage / MDX / FAQ / Recipes / Theming / Props
• Announcements: Vision / DocsPage / MDX / Framework support
• Example: Storybook Design System