Modes

A Mode is a specific value for an Addon. Every addon accepts a range of values. The Theme Addon, for example, accepts multiple themes. When you select "Light" or "Dark" in the Widgetbook UI, you are switching the theme mode, and the story re-renders with that theme applied.

In scenarios, modes are set explicitly so that each test run uses the same fixed configuration.

Modes vs Args

Args control widget properties like text, color, or state. Modes control the environment the widget renders in, such as theme, locale, or viewport.

Usage in Scenarios

Pass modes in the modes list of a _Scenario:

final $Default = _Story(
  scenarios: [
    _Scenario(
      name: 'Dark iPhone',
      modes: [
        MaterialThemeMode('Dark', ThemeData.dark()), 
        ViewportMode(IosViewports.iPhone13), 
      ],
    ),
  ],
);

Each built-in addon has a corresponding Mode class. See the individual addon pages for which Mode to use.

Story-level Modes

Modes defined on a story apply to all its scenarios. In the following example, both scenarios inherit the Dark theme and iPhone 13 viewport:

final $Button = _Story(
  modes: [
    MaterialThemeMode('Dark', ThemeData.dark()), 
    ViewportMode(IosViewports.iPhone13), 
  ],
  scenarios: [
    _Scenario(name: 'Default'),
    _Scenario(name: 'Loading', args: _Args.fixed(isLoading: true)),
  ],
);

Mode Merging

When both a story and a scenario define modes, they are merged. Scenario-level modes take precedence for the same mode type:

final $Button = _Story(
  modes: [
    MaterialThemeMode('Dark', ThemeData.dark()),
    ViewportMode(IosViewports.iPhone13),
  ],
  scenarios: [
    _Scenario(
      name: 'Light Override',
      modes: [
        MaterialThemeMode('Light', ThemeData.light()), 
      ],
    ),
  ],
);

The Light Override scenario runs with the Light theme (overridden by the scenario) and the iPhone 13 viewport (inherited from the story).

For full details on merging behavior, see How Modes Are Merged.

Custom Modes

To create a Mode for a custom addon, extend the Mode class with your addon's setting type:

class BorderMode extends Mode<BorderSetting> {
  BorderMode(double width, Color color)
    : super(
        BorderSetting(width, color),
        BorderAddon(),
    );
}

See the Custom Addon page for a full example.