Essential Addons

Let's dive into the addons that come with the default Storybook template.

Storybook Addons

As mentioned in previous lessons, you can install Storybook addons to provide extra functionality to your Storybook. Once installed, they can be located in the toolbar at the top or in a dedicated addon panel:

If you don't see the addon panel when running Storybook, you can type A, the shortcut to show/hide the addons panel or click on the shortcuts button at the top left and select Show addons:


In the Storybook addons official page, you can explore a vast amount of addons (both official and from the community) for all different scenarios – accessibility testing, design tool integrations, etc.

When you install Storybook via the CLI command (like we did in this module), it already comes with addon-essentials installed, which is a bundle of official addons maintained by Storybook maintainers. Let's quickly go over them.

Addons - Actions

Actions is an addon that helps visualize when components emit events. If your component has functions like onClick, onDrag, onSubmit, etc., whenever those event handlers are fired, they will be logged in the addon actions panel, along with the data they emit.

Addons can be configured by using parameters, which just like args, argTypes and decorators, are annotations that can be applied globally (in preview), at the component level (meta) or for a single story.

In our project, Storybook globally preconfigured addon actions by passing the following parameter to preview.js:

// .storybook/preview.js
export const parameters = {
  // transform any arg whose name matches this regex into an action
  // Examples: onClick, onHover, onAccountSelect etc.
  actions: { argTypesRegex: "^on[A-Z].*" }
}

The automatic transformation of args into actions works because addons have access to a story's args, which we set in the meta in our stories files. If you forget to set it, this configuration will not work!

You can also learn more about configuring the addon here.

Addons - Viewport

Viewport is an addon that allows your stories to be displayed in different layouts and sizes to help you build responsive components. It comes with basic options like small, medium, and large devices, but you can extend it to contain a list of devices like iPhone X, Pixel, etc., or even create your own options with breakpoints from your project.

You can configure the addon by defining the viewport parameter, by either passing your own breakpoints for your app, or you can optionally use a predefined list of device breakpoints which are available from the library. Let's add this list in the preview.js file:

// .storybook/preview.js
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport'

export const parameters = {
  viewport: {
    viewports: INITIAL_VIEWPORTS
  }
}

// ... rest of code removed for brevity

You should be able to see a list of devices now:

You can also learn more about configuring the addon here.

Addons - Docs

Docs is an addon that provides support for authoring stories in MDX format, and also turns your components into living documentation. Out of the box, it will scan your components and automatically detect their metadata, providing you with a new tab called Docs. In this tab, you can see the primary story of your component, its source code, a table of its properties and their types, and even a way to change them at runtime and see your component responding to the changes, plus all its variations. This is also thanks to args. Docs takes advantage of the property component from a story's meta, and if you don't provide it, Storybook won't be able to fully scan your component for information.

You can learn more about all of its potential here.

Addons - Controls

Controls is an addon that automatically scans the properties from each of your stories and gives you a UI to interact with them at runtime. Its functionality is similar to the one in docs but presented in the addons panel. This is only possible if your stories use args. Similar to docs, Controls takes advantage of the property component from a story's meta.

Additionally, we can see that Storybook added some custom configuration to addon controls in preview.js called control type matchers which you can set a regex to automatically turn args that match them into either color or date pickers:

// .storybook/preview.js
export const parameters = {
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    }
  }
}

// ... rest of code removed for brevity

Additionally, you can configure the controls panel to also show descriptions from jsdoc coming from your components' comments. You can set a expanded flag like so:

// .storybook/preview.js
export const parameters = {
  controls: {
    expanded: true,
    //... rest of the code
  }
}

// ... rest of code removed for brevity

And you can see how the jsdoc translates to the addon panel:

You can also learn more about configuring the addon here.

Addons - Backgrounds

Backgrounds is an addon to help visualize how your components look in different backgrounds. This is quite helpful when experimenting with different background colors, and designers can take advantage of it. It also includes a grid utility that helps you better align elements within your components.

You can define your own list of backgrounds, though it already comes with light and dark as examples. You can also set the default background for a given story. Let's set the default background for the Primary button story:

// src/stories/Button.stories.tsx

// ... rest of the code removed for brevity

export const Primary = Template.bind({});
Primary.parameters = {
  backgrounds: {
    default: 'dark'
  }
}

And once we visit the story, it should look like this:

Info

The selected backgrounds are saved in the URL as query params, so that the user choice is persisted. If you want to fully reset backgrounds, you might have to remove the query params from the URL.

You can also learn more about configuring the addon here.

Addons - Toolbars

Toolbars is an addon that controls global rendering options for your stories. It's a general-purpose addon that can be used to achieve things such as:

  • Creating a theme switcher (which we will be doing in this course)
  • Creating a language swi