Themes in modes

Themes control the visual characteristics of UI—color palette, typography, white space, border styles, shadows, radii, etc. Using modes enables Chromatic to test the same story with multiple themes.

Configure CSS and theme in your Storybook

There are various ways to configure Storybook for loading CSS and applying themes. Our recommendation is to use @storybook/addon-themes, which is a framework-agnostic solution compatible with most popular tools. For tool-specific setup instructions, please refer to the recipes provided below:

• Emotion
• @mui/material
• bootstrap
• styled-components
• tailwind
• vuetify@3.x

Don’t see your favorite tool listed? No worries! You can check out the “Writing a custom decorator” guide in the Storybook Themes API documentation to get started.

For this example, let’s assume that the themes addon has been configured with a light theme and a dark theme:

// .storybook/preview.js

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

import '../src/index.css';

const preview: Preview = {
  parameters: {
    /* ... */
  },
  decorators: [
    withThemeByClassName({
      themes: {
        light: 'light',
        dark: 'dark',
      },
      defaultTheme: 'light',
    }),
  ],
};

export default preview;

Define theme modes

Modes are defined in the .storybook/modes.js file. If your project doesn’t have this file yet, go ahead and create it. To enable a theme within a mode, specify the theme name using the chromatic[mode_name].theme parameter.

// .storybook/modes.js

export const allModes = {
  light: {
    theme: "light",
  },
  dark: {
    theme: "dark",
  },
};

Apply modes to enable themes

Modes can be applied at various levels: project, component, or story. If a mode includes a valid theme parameter, Chromatic will apply the corresponding theme when capturing the snapshot.

With the above set of modes, we can apply them as follows:

// ArticleCard.stories.js

import { allModes } from "../.storybook/modes";
import { ArticleCard } from "./ArticleCard";

export default {
  component: ArticleCard,
  title: "ArticleCard",
  parameters: {
    chromatic: {
      //🔶 Test each story for ArticleCard in two modes
      modes: {
        light: allModes["light"],
        dark: allModes["dark"],
      },
    },
  },
};

export const Base = {
  args: {
    //...
  },
};

When Chromatic captures your story, it will capture two snapshots during the build, with the corresponding theme enabled. Each mode will have an independent baselines and require distinct approval.