Toolbars and Globals

Purpose and Scope

Toolbars and globals solve the problem of changing cross-cutting preview context without editing every story. A global is a Storybook-level value that is not specific to a single story function. Common examples include theme, locale, color mode, feature flag mode, or the built-in background and viewport selections. The documented workflow is to define a global, expose it as a toolbar control, and then read it from story context inside decorators so the rendered story updates consistently when the user changes the toolbar selection.

Sources: docs/essentials/toolbars-and-globals.mdx

This is different from story args. Args are inputs passed to the story and usually model component props or component state. Globals are available as context.globals, not through the args argument, because they describe the environment around the story rather than the story itself. That distinction matters when you are deciding where to place configuration: component variants belong in args, while preview-wide state such as the active theme belongs in globals and decorators. When a global changes, Storybook re-renders the story and re-runs decorators with the new values.

Sources: docs/essentials/toolbars-and-globals.mdx

Relevant Source Files

• docs/essentials/toolbars-and-globals.mdx - The official documentation source for the Toolbars & globals Essentials page. It defines globals, explains globalTypes and toolbar annotations, shows how decorators consume context.globals, and describes story or component globals overrides.

Core Primitives

The first primitive is globalTypes. In .storybook/preview.*, globalTypes declares the shape of a global and attaches a toolbar annotation so Storybook can render a toolbar dropdown or menu for it. The docs describe this as a simple declarative syntax: the preview configuration owns the definition, and when Storybook starts, the manager UI can show a new toolbar item such as a theme selector with light and dark choices. Because globals are truly global, the docs explicitly restrict globalTypes and initialGlobals to .storybook/preview.*.

Sources: docs/essentials/toolbars-and-globals.mdx

The second primitive is initialGlobals. It sets the starting value for a global before the user interacts with the toolbar. This is useful when a Storybook should boot into a default theme, locale, or environment that matches the project baseline. The toolbar remains interactive unless a story or component overrides that global. Treat initialGlobals as the default, not as a permanent lock: it establishes the initial preview state, while the toolbar lets users explore alternate global states during development and review.

Sources: docs/essentials/toolbars-and-globals.mdx

The third primitive is the decorator. A decorator wraps stories and can provide the context required by the selected global. The docs use theming examples across frameworks: a React project might wrap stories in a styled-components theme provider, a Vue project might wire in Vuetify, and an Angular project might integrate Angular Material. The common pattern is the same regardless of renderer: read context.globals.theme, choose the matching framework or design-system configuration, and render the story inside the provider or wrapper that applies it.

Sources: docs/essentials/toolbars-and-globals.mdx

Configuration Reference

A minimal preview setup follows the documented shape even when the exact snippet is project-specific. Define the global type, give it toolbar metadata, set an initial value, then consume the value in a decorator. The important design constraint is locality: put the global definition and initial value in .storybook/preview.*, not in individual story files. Individual stories can still opt into a forced value later by using the globals annotation, but the global itself is part of preview configuration.

// .storybook/preview.ts
export const globalTypes = {
  theme: {
    description: 'Global theme for components',
    toolbar: {
      title: 'Theme',
      items: ['light', 'dark'],
    },
  },
};
 
export const initialGlobals = {
  theme: 'light',
};
 
export const decorators = [
  (Story, context) => {
    const theme = context.globals.theme;
    return <ThemeProvider theme={theme}><Story /></ThemeProvider>;
  },
];

Sources: docs/essentials/toolbars-and-globals.mdx

Execution Flow

At runtime, the reader-facing flow starts in .storybook/preview.*. Storybook loads the preview configuration, sees the declared globalTypes, and uses the toolbar annotation to add an item to the toolbar. The value begins with initialGlobals when configured. As the user changes the dropdown, the selected value becomes part of context.globals. Storybook then re-renders the active story and re-runs decorators, which lets wrappers such as theme providers, locale providers, or environment providers react to the new value without changing the story source.

Sources: docs/essentials/toolbars-and-globals.mdx

This flow is especially useful because it keeps reusable component states separate from reusable rendering context. A button story can still describe whether the button is primary, disabled, or loading through args, while the global theme can switch the entire preview between light and dark. That separation makes stories easier to reuse in documentation and tests because the component state remains explicit, while the global environment can be changed by the toolbar or by a targeted override when a story requires a fixed environment.

Sources: docs/essentials/toolbars-and-globals.mdx

Story-Level and Component-Level Overrides

Sometimes a story should not inherit whatever the reviewer last selected in the toolbar. The docs call out cases where a specific global value is required for correct rendering, such as testing against a particular environment. For that case, set the globals annotation on the story or component meta. Storybook then forces that value for the affected stories and disables the toolbar menu for that global while viewing them. This prevents accidental mismatches between the intended scenario and the current toolbar state.

Sources: docs/essentials/toolbars-and-globals.mdx

The documented backgrounds example illustrates the same contract for built-in globals. A component can force all of its stories to use a gray background, while a specific story can override that with a dark background. The principle applies equally to custom globals such as theme or locale: use the toolbar for exploration across the Storybook, and use globals annotations only where the scenario has a required global value. Overusing overrides reduces the value of the toolbar because users lose the ability to switch context freely.

Sources: docs/essentials/toolbars-and-globals.mdx

Implementation Guidance

Use globals when the value controls the preview environment rather than the component API. Good candidates include theme, color scheme, locale, text direction, authenticated state, or feature mode. Avoid using globals for per-component variations that belong in args, because that makes stories harder to understand and harder to compose. The documentation places globals next to Essentials features such as viewport and backgrounds because they share the same user experience: a toolbar control changes how the story is rendered in the preview frame.

Sources: docs/essentials/toolbars-and-globals.mdx

When adding a new toolbar global, start with a small, named set of options and make the decorator responsible for translating the selected value into framework-specific behavior. For a design-system theme, the toolbar item can expose stable labels such as light and dark, while the decorator maps those labels to the actual theme objects, providers, or CSS classes. Keep that mapping close to the preview decorator so story authors can rely on the global without duplicating provider setup across every story file.

Sources: docs/essentials/toolbars-and-globals.mdx

Next Steps

After defining a toolbar global, verify three things in a running Storybook: the toolbar item appears, switching it re-renders the active story, and the decorator receives the expected value through context.globals. Then add any required story or component globals overrides only for scenarios that must lock the environment. For adjacent concepts, read the pages on decorators, backgrounds, viewport, and story args so your project uses the right Storybook surface for each kind of state.