wc-toolkit
WC Toolkit Storybook Helpers
These helpers are designed to make integrating Web Components with Storybook easier.
There are a number of things that this helper library does to provide developers a better experience with Storybook and Web Components:
- Uses types to provide better controls
- Prevents name collisions when attributes, properties, slots, and CSS shadow parts share the same name
- Provides a template with bindings for attributes, properties, CSS custom properties, and CSS shadow parts.
- Provides two-way binding for controls and attributes in the template to help keep control values in sync with the component
Be sure to check out the official docs for more information on how to configure and use this.
Before You Install
- If you don't already have it installed, follow the installation steps in the Storybook docs for web components
npm create storybook@latest- Load your custom elements manifest into Storybook in the
.storybook/preview.jsfile:
// .storybook/preview.js
import { setCustomElementsManifest } from "@storybook/web-components-vite";
import manifest from "./path/to/custom-elements.json" with { type: "json" };
setCustomElementsManifest(manifest);- Add the expanded controls to your config in the
.storybook/preview.jsfile:
export const parameters = {
...
controls: {
expanded: true,
...
},
}Installation
Now that you have Storybook installed, you can install the helpers:
npm i -D @wc-toolkit/storybook-helpersNext, if you have global configurations, set those in your Storybook config in the .storybook/preview.js file:
// preview.js
import { setStorybookHelpersConfig, type Options } from "@wc-toolkit/storybook-helpers";
const options: Options = {...}
setStorybookHelpersConfig(options);Setup
Import the storybook helpers into your story and get the appropriate helpers by passing your element's tag name into the Storybook helper function.
the function will return the helper data you can assign to the Storybook meta object.
// my-element.stories.ts
import type { Meta, StoryObj } from "@storybook/web-components-vite";
import { getStorybookHelpers } from "@wc-toolkit/storybook-helpers";
const { events, args, argTypes, template } =
getStorybookHelpers<MyElement>("my-element");
const meta: Meta<MyElement> = {
title: "Components/My Element",
component: "my-element",
args,
argTypes,
render: (args) => template(args),
parameters: {
actions: {
handles: events,
},
},
};
export default meta;The function returns the following:
events: an array of events that will be captured in the actions tabargs: this provides the default values for the componentargsargTypes: an object tha configures the controls for the component based on the data from the Custom Elements Manifesttemplate: a function that will return a template for the component as well as provide two-way data binding for the component's API and the Storybook controls
Be sure to check out the official docs for more information on how to configure and use this.