Introducing the Theme Switcher addon

Today, we’re thrilled to introduce Storybook’s first dedicated Theme Switcher addon: @storybook/addon-themes!

Read on to learn how the addon works, plus all our latest news from the last month.

Why the Theme Switcher addon?

There are many times when you’ll want to test different themed versions of your UI and components. A popular use case is when you’re testing components in different color schemes. Maybe you’re testing out how your UI looks in light mode and dark mode, for example.

One way to do this (although we wouldn’t recommend it) would be to create Storybook stories for each color scheme of your components. If you’re anything like me, though, that’s going to get very unwieldy as your UI grows.

Historically, the way to solve this is by creating your own theme switcher within Storybook. We’ve shared tutorials for doing this in the past.

The new Theme Switcher addon (@storybook/addon-themes) takes this ease one step further. It brings you a custom theme switcher straight out the box. That lets you switch between different themes inside your stories, without having to write stories for each different theme!

Try it now

To get started with the Theme Switcher addon, head to your Storybook project and run npm i -D @storybook/addon-themes.

Then, head to your main.js or main.ts file. If the file contains an addons array, add @storybook/addon-themes into it. If the file doesn't have an addons array, copy and paste the example below.

Then, declare your themes with one of the decorators provided by @storybook/addon-themes. If you’re using a theme provider component, use withThemeFromJSXProvider. If you’re switching themes with a CSS class, use withThemeByClassName. Lastly, if you’d prefer switching themes through data attributes, use withThemeByDataAttribute.

// .storybook/preview.ts
import { withThemeByClassName } from '@storybook/addon-themes';

export default {
  decorators: [
    withThemeByClassName({
      themes: {
        light: 'light-theme',
        dark: 'dark-theme',
      },
      defaultTheme: 'light',
    }),
  ],
};

Learn more about providing themes to your stories (via decorators) by checking out Chantastic’s tutorial below!

Wait, wasn’t this part of the Styling addon? 🧐

Historically, yes!

However, we found that the Styling addon ended up doing way too much. Alongside letting you switch story themes, the Styling addon configured styling in Webpack projects and contained autoconfig scripts. Very few projects needed all of these.

So, we recently divided @storybook/addon-styling into three new lightweight packages. These can be installed to meet your project’s needs.

These new packages are:

• @storybook/addon-themes (as already mentioned!)
• @storybook/addon-styling-webpack: Use this to configure Storybook for styling tools in your Webpack Storybook.
• @storybook/auto-config: This is an npx-able script that will read your project and configure @storybook/addon-styling-webpack and/or @storybook/addon-themes for you. Try it by running npx @storybook/auto-config styling or npx @storybook/auto-config themes!

At the same time, we’ll be deprecating the Styling addon. To learn more, head to the Styling addon migration guide, or contact our maintainers in the Storybook Discord.

Add command in Storybook CLI

As a bonus, you can now also use Storybook CLI’s add command to install and register an addon!

For addons that have a post-install script (like @storybook/addon-styling-webpack and @storybook/addon-themes), it runs the autoconfig scripts automatically. Get started by using npx storybook@latest add @storybook/addon-styling-webpack.

Visual Test addon — private beta coming soon

We’ve made some great progress on the Visual Test addon, which lets you run Chromatic’s automated visual tests inside your Storybook. The addon entered private alpha at the start of September. Since then, we’ve completed work on its core visual testing workflow.

Now, our team of six maintainers are focusing on improving the addon’s onboarding experience. We’re also refining the addon’s performance to ensure it only takes snapshots of stories that have changed.

The Visual Tests addon is heading to private beta at the end of this month. If you’re already signed up to our early access list, we look forward to sharing the addon with you soon! And if you haven’t: sign up here!

London, Toronto, and Paris meetups

A major highlight from September was that we held our first-ever Storybook meetup in the UK! Over 100 devs were joined by speakers from Figma, Storybook, and Immediate Media to explore the theme of dev-design handoffs. It was a fantastic night and brilliant to meet so many members of our community!

Next up: we have two events coming in October and November!

🇨🇦 Toronto, October 24th: Join us for an evening social with speakers from Rangle, Wealthsimple, and Chromatic, exploring the topic of UI testing. RSVP 👉

🇫🇷 Paris, November 7th: Our first France meetup! Cohosted with the Design System team at Back Market, the night will explore the theme of design system tooling and automation. There’ll be presentations by leading design system engineers and Storybook maintainers. RSVP 👉

Storybook 7.4 and 7.5 alpha

Within the last month, we shipped Storybook 7.4 and entered the alpha for Storybook 7.5. Both are packed full of fixes and improvements made by our maintainers and our community. Thank you to all our contributors for helping make Storybook the best it can be!

Check out all the PRs that went into SB 7.4 and 7.5 👉

If you’re interested in contributing to Storybook, there’s no better time to start than now! We regularly go through GitHub Issues and identify ‘good first issues’ for first-time contributors. Check them out!

New learning resources

Finally, here are the new learning resources that we shared last month!

Three ways to quickly set up Storybook

How to theme your Storybook

Component testing IRL

That’s all for this month! Thanks for reading, and we’ll look forward to bringing you the next update in October. Until then: for all updates from the community, follow us on social media!