Backgrounds

Purpose and Scope

Backgrounds are an Essentials feature for controlling the canvas color behind a rendered story. The feature solves a practical component-development problem: many components are designed for a particular surface, but stories are often reviewed in isolation. A button, card, modal, or navigation element may need to be checked on a dark page, a branded marketing color, or a transparent-looking neutral surface. Storybook exposes those surfaces through a toolbar selector, so authors and reviewers can change context without editing component code or leaving the running Storybook.

Sources: docs/essentials/backgrounds.mdx

The source documentation places Backgrounds alongside the other Essentials because it is meant to be available during everyday story browsing, not only during specialized testing. By default, Storybook provides light and dark backgrounds, which gives a project an immediate baseline. Project teams can then replace or extend that baseline with colors that match their design system. This makes the preview iframe a closer approximation of real application surfaces while preserving Storybook's isolated authoring model, where the story remains focused on one component state at a time.

Sources: docs/essentials/backgrounds.mdx

Relevant Source Files

docs/essentials/backgrounds.mdx — Defines the reader-facing Backgrounds documentation, including configuration in preview files, story-level globals, parameter inheritance, disabling behavior, grid support, and the public globals and parameters contributed under the backgrounds namespace.

Core Concepts

The feature has two related concepts: the available background choices and the selected background for a rendered story. Available choices are configured as parameters, while fixed selections are expressed through globals. This distinction matters because parameters describe how the feature is configured for a project, component, or story, whereas globals describe active preview state. The documentation specifically notes that a story or component can be given a background through globals, and that doing so locks the selection so it cannot be changed from the toolbar for that scope.

Sources: docs/essentials/backgrounds.mdx

A typical project-level setup belongs in the preview configuration file. The documentation names .storybook/preview.* as the place to define the shared set of colors through the backgrounds parameter and to set the initial selected color through initialGlobals. That placement means every story starts from the same design-system vocabulary. Authors can still refine behavior later at narrower scopes, but the preview-level configuration is the right place for organization-wide defaults such as light, dark, brand, or application shell surfaces.

Sources: docs/essentials/backgrounds.mdx

Configuration Flow

Start by deciding which surface names should be visible to people browsing stories. The options property defines the available background colors, and each option should be treated as a stable key that story authors can reference. Then choose an initial global value that reflects the most common review surface. This two-step setup keeps the toolbar useful for exploratory development while making first render predictable. If your component library has a documented color palette, align the option names with that vocabulary so reviewers recognize the choices immediately.

Sources: docs/essentials/backgrounds.mdx

// .storybook/preview.ts
const preview = {
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#ffffff' },
        dark: { name: 'Dark', value: '#111111' },
        brand: { name: 'Brand', value: '#1EA7FD' },
      },
    },
  },
  initialGlobals: {
    backgrounds: { value: 'light' },
  },
};
 
export default preview;

For a single story, use globals when the background is part of the state being demonstrated rather than a browsing convenience. The documentation calls out that a color set this way is applied and cannot be changed with the toolbar. That behavior is useful for examples where contrast, visual hierarchy, or brand treatment is essential to the story's meaning. For instance, a white logo variant should not accidentally be reviewed on a white canvas, and a notification designed for a dark surface should remain on that surface in screenshots and demos.

Sources: docs/essentials/backgrounds.mdx

Parameter Inheritance and Overrides

Background configuration participates in Storybook parameter inheritance. The documentation describes extending configuration on a per-component or per-story basis, which lets teams keep global defaults while making targeted adjustments. Component-level options are a good fit when every story for a component needs a narrower set of surfaces. Story-level overrides are better when only one example has a special requirement. This layered model avoids duplicating the whole project configuration in every story file and keeps Backgrounds consistent with the broader Storybook parameter system used by addons.

Sources: docs/essentials/backgrounds.mdx

Disabling follows the same inheritance pattern. The backgrounds parameter includes a disable flag that turns off the feature's behavior. The documentation highlights a common reason for using this at a specific level: a project may disable the feature globally, then re-enable it for a component or story by setting the value back to false at a more specific level. Disable the feature when a story already renders a full-page shell, when the component intentionally controls its own page surface, or when a visual test should avoid toolbar-driven canvas changes.

Sources: docs/essentials/backgrounds.mdx

Grid Support

Backgrounds also includes a grid selector for quickly checking alignment. The grid does not require extra setup to begin using it, but its behavior can be customized through the backgrounds grid parameter. The documented grid configuration includes cellAmount, cellSize, disable, offsetX, offsetY, and opacity. The defaults shown in the source include a minor-grid size of five and a major-grid size of twenty, with offset defaults related to story layout. Use the grid during layout work, spacing review, and responsive adjustments, then disable it where it would distract from the story.

Sources: docs/essentials/backgrounds.mdx

const preview = {
  parameters: {
    backgrounds: {
      grid: {
        cellAmount: 5,
        cellSize: 20,
        opacity: 0.5,
      },
    },
  },
};

API Reference

The Backgrounds feature contributes globals under the backgrounds namespace. The grid global is a boolean that controls whether the grid is displayed. The value global is a string that selects the applied background and must match the key of one of the configured color options. When value is set for a story or component, the toolbar cannot change the selection for that scope. The feature also contributes parameters under the same namespace: disable controls feature behavior, grid configures the alignment grid, and options defines the available color choices.

Sources: docs/essentials/backgrounds.mdx

Next Steps

After configuring project defaults, review key stories in the running Storybook and confirm that the toolbar choices match the design surfaces your team actually uses. Move fixed backgrounds into story or component globals only when the background is part of the example's correctness. Use per-component options for specialized components, such as inverse logos or cards meant for a narrow set of containers. For related configuration concepts, read the pages on Parameters, Toolbars and Globals, Viewport, and Story Rendering and Layout, because those features use the same layered configuration ideas.

Ask a question...