Addons extend Storybook with features and integrations that are not built into the core. Most Storybook features are implemented as addons. For instance: documentation, accessibility testing, interactive controls, and design previews. The addon API makes it easy for you to configure and customize Storybook in new ways. There are countless addons made by the community that unlock time-saving workflows. What addons can do:
Browse the addon gallery to install an existing addon or as inspiration for your own addon. Read on to learn how to make an addon yourself.
Before writing your first addon, let’s take a look at the basics of Storybook’s architecture. While Storybook presents a unified user interface, under the hood it’s divided down the middle into Manager and Preview.
The Manager is the UI where Storybook’s search, navigation, toolbars, and addons are rendered. The Preview area is an iframe where stories are rendered.
Because Manager and Preview run in separate iframes, they communicate across a communication channel. When you select a story within the Manager an event is sent across the channel and the selected story is rendered inside the Preview.
Many of the addon APIs you’ll read about below are abstractions to help make this communication transparent.
Let’s write a simple addon for Storybook which:
Let’s start by writing a story for our addon that exposes a custom parameter. The idea is that our addon will show this parameter in the addon panel.
Because we added the story at the component level, the
myAddon parameter is associated with all stories defined in the file.
Now let’s add a panel to Storybook in a file called
register.js, which is the entry point for addons to register themselves.
This is boilerplate code for any addon that adds a panel to Storybook, and there’s really not much going on here. In this case, we’re just adding a static div that renders when the panel is selected in Storybook’s UI.
Next, let’s replace the
MyPanel component from above to show the parameter.
The new version is made smarter by
useParameter, which is a React hook that updates the parameter value and re-renders the panel every time the story changes.
The addon API provides hooks like this so all of that communication can happen behind the scenes. That means you can focus on your addon's functionality.
Finally, let’s hook it all up. Addons are typically published as standalone packages, but they can also be written locally in an existing Storybook project. We’ll make our addon a local addon.
The path can be an absolute location on your file system, or a path relative to your
.storybook directory (e.g.
./my-addon/register.js if you defined the addon inside your
If you get an error similar to:
It is likely because you do not have a
.babelrc file or do not have it configured with the correct presets:
Now restart/rebuild Storybook and your addon should appear in the addons panel. Furthermore, as you navigate between stories, the parameter displayed should update accordingly.
In the previous example, we introduced the structure of an addon, but barely scratched the surface of what addons can do.
To dive deeper we recommend Learn Storybook’s “creating addons” tutorial. It’s an excellent walkthrough that covers the same ground as the above introduction, but goes further and leads you through the full process of creating a realistic addon.
Once you understand the basics of writing an addon, there are a variety of common enhancements to make your addon better.
It’s possible to disable the addon panel for a particular story.
To make that possible, you need to pass the
paramKey element when you register the panel:
Then when adding a story, you can pass a disabled parameter.
Storybook uses Emotion for styling, AND we provide a theme which can be set by the user!
We recommend you also to use Emotion to style your addon’s UI components. That allows you to use the active Storybook theme to deliver a seamless developer experience.
If you don’t want to use Emotion, you can use inline styles or another css-in-js lib. You can receive the theme as a prop by using the
withTheme hoc from Emotion. Read more about theming.
Addon authors can develop their UIs using any React library. But we recommend using Storybook’s own UI components in
@storybook/components to build addons faster. When you use Storybook components you get:
You can check them out in Storybook’s own storybook
In the example above, we showed how to write a local addon inside an existing Storybook project. To distribute your addon for others, package the addon into a standalone NPM module.
For a good template of an addon packaged as an NPM module, check out @storybook/addon-controls.
It contains addon code similar to what we’ve written above. It also contains:
register.jsfile at the root level written as an ES5 module
srcdirectory containing the ES6 addon code
distdirectory containing transpiled ES5 code on publish
Your packaged Storybook addon needs to be written in ES5. If you are using ES6, then you need to transpile it.
When you are developing your addon as a package, you can’t use
npm link to add it to your project. Instead add your package as a local dependency into your package.json:
Storybook presets are collections of Storybook configurations that get applied automatically when you create a
/preset.js entry point in your addon and then list that addon in your project’s
.storybook/main.js addons field.
Common uses for presets include:
Here’s an example of typical preset file:
For more information on presets, see the presets docs.
If you want to learn more about how you can write your own presets, read the documentation
If you want to expand your knowledge on the Addons API, read the documentation