Storybook story modes

Capture separate Storybook snapshots for each mode, combining theme, viewport, and locale globals in Argos.

Argos can capture multiple versions of your stories by applying different “modes,” which are essentially combinations of global Storybook settings (such as theme, viewport, locale, etc.). With modes, you can automatically generate a separate snapshot for each unique configuration.

If you already have parameters.chromatic.modes, Argos will handle those settings by default. Prefer parameters.argos.modes in new work.

What are modes?

A mode is a preset that configures various Storybook globals. For instance, you can have a “dark” mode for your UI theme, a “mobile” mode for smaller screens, or a combined “dark-mobile-spanish” mode that configures multiple globals at once.

Key features of modes:

• Each mode is named (e.g., "dark desktop" or "mobile").
• Each mode sets specific values for the Storybook globals (e.g., viewport size, background color, locale).
• Argos creates a separate visual baseline for each mode name.

Setting up globals & addons

Before you define any modes, make sure you’ve configured the relevant Storybook features and addons in your .storybook/preview.ts (or .js) file. Examples include:

• Viewports and backgrounds, built into Storybook 9 and later (on Storybook 8, install @storybook/addon-viewport and @storybook/addon-backgrounds)
• @storybook/addon-themes for light/dark themes
• storybook-i18n for locales

These features rely on Storybook “globals” and “decorators” under the hood. Argos modes simply set those globals at test time to generate multiple snapshots of the same story.

.storybook/preview.ts

import { withThemeByClassName } from "@storybook/addon-themes";
import "../src/styles.css";

const preview = {
  parameters: {
    viewport: {
      options: {
        compact: {
          name: "Compact",
          styles: { width: "600px", height: "900px" },
        },
        widescreen: {
          name: "Widescreen",
          styles: { width: "1440px", height: "900px" },
        },
      },
    },
    backgrounds: {
      options: {
        light: { name: "Light", value: "#ffffff" },
        dark: { name: "Dark", value: "#1A1A1A" },
      },
    },
  },
  decorators: [
    withThemeByClassName({
      themes: {
        light: "light",
        dark: "dark",
      },
      defaultTheme: "light",
    }),
  ],
};

export default preview;

On Storybook 8, viewports are defined under viewport.viewports and backgrounds under backgrounds.values (an array of { name, value }), and a mode selects a background by its color, for example backgrounds: { value: "#1A1A1A" }. Argos resolves a mode’s viewport against either format.

Defining modes

Create a .storybook/modes.ts (or .js) file that exports an object where each key is a mode name and each value is a set of overrides for the Storybook globals. For example:

.storybook/modes.ts

export const allModes = {
  dark: {
    backgrounds: { value: "dark" },
    theme: "dark",
  },
  mobile: {
    viewport: "compact",
  },
  "dark widescreen": {
    backgrounds: { value: "dark" },
    theme: "dark",
    viewport: "widescreen",
  },
  "light mobile": {
    backgrounds: { value: "light" },
    theme: "light",
    viewport: "compact",
  },
};

Each object can include as many or as few globals as you need. If a mode doesn’t specify a particular global, that global simply won’t be changed in that mode.

A mode’s viewport is a key of your viewport.options map: Argos resizes the browser to that viewport before capturing the story. Storybook’s own global format works too, so viewport: { value: "compact", isRotated: true } captures the viewport in landscape orientation. Likewise, backgrounds.value is a key of backgrounds.options, and theme is the global read by withThemeByClassName.

Applying modes

Attach modes to any level of your Storybook: globally in .storybook/preview.ts (or .js), at the component (default export) level, or in an individual story’s parameters. Argos merges all modes defined up the chain.

Basic usage in a story file

ProductCard.stories.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from "@storybook/your-framework";

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

const meta = {
  title: "Components/ProductCard",
  component: ProductCard,
  parameters: {
    // Use Argos for new projects; Chromatic is recognized too
    argos: {
      modes: {
        mobile: allModes.mobile,
        dark: allModes.dark,
      },
    },
  },
} satisfies Meta<typeof ProductCard>;

export default meta;
type Story = StoryObj<typeof meta>;

export const DefaultView: Story = {
  args: {
    productName: "Coffee Beans",
    price: 9.99,
  },
};

export const SoldOutView: Story = {
  args: {
    productName: "Coffee Beans",
    price: 9.99,
    isSoldOut: true,
  },
};

In this example, Argos will generate two snapshots for each story (DefaultView and SoldOutView): one in “mobile” mode and another in “dark” mode.

Combining modes from multiple levels

You can add modes in your .storybook/preview.ts (or .js) at the project level, then define additional modes in a story file. Argos merges the modes defined at every level and captures one snapshot per mode name.

Project-level modes

.storybook/preview.ts

import { allModes } from "./modes";

const preview = {
  parameters: {
    argos: {
      modes: {
        "light mobile": allModes["light mobile"],
      },
    },
  },
};

export default preview;

Component-level modes

ProductCard.stories.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from "@storybook/your-framework";
import { ProductCard } from "./ProductCard";
import { allModes } from "../../../.storybook/modes";

const meta = {
  title: "Components/ProductCard",
  component: ProductCard,
  parameters: {
    argos: {
      modes: {
        "dark widescreen": allModes["dark widescreen"],
      },
    },
  },
} satisfies Meta<typeof ProductCard>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  args: {
    /* ... */
  },
};

When Argos runs, it will generate snapshots for each mode defined at the project level and the component level. So for Basic, you get “light mobile” (from preview.ts) plus “dark widescreen” (from the component’s parameter).

Excluding or disabling modes

Sometimes you want to turn off a certain higher-level mode for a specific story. You can do this by passing a disable property:

ProductCard.stories.ts

// ...

export const SpecialCard: Story = {
  args: {
    /* ... */
  },
  parameters: {
    argos: {
      modes: {
        "light mobile": { disable: true }, // turns off this inherited mode
      },
    },
  },
};

That story will now ignore light mobile mode but still apply any other inherited modes.

Working with baselines

Each mode name corresponds to a separate baseline in Argos. If you rename a mode, it’s treated as entirely new. If you alter the internals of a mode (like changing the viewport from “compact” to “ultra-compact”) without renaming it, Argos still compares the new screenshot against the old baselines for that mode name.

If you have an original single baseline from before you introduced modes, and you want to keep it around, just add a mode like "baseline" that reproduces the same environment as the original story. That way, your old baseline is preserved while you experiment with new modes.

FAQ

Can modes be applied if I'm still using parameters.chromatic?

Yes. Argos reads your chromatic.modes settings if present. However, for new users or updated setups, prefer using argos.modes to avoid any confusion in the future.

Do all Storybook addons work with Argos modes?

Any feature or addon that leverages Storybook globals should work, including Storybook’s built-in viewports and backgrounds, @storybook/addon-themes, or storybook-i18n. Modes just provide different values for those globals.

What happens if I delete or rename a mode?

If you remove a mode from your code, Argos will stop capturing new snapshots for that mode, and its baseline history won’t be updated anymore. Renaming a mode effectively creates a new baseline, much like renaming a story.

By setting up modes for dark vs. light, mobile vs. desktop, and everything in between, you verify all key variants of your UI without writing extra stories.