How to Use the Backgrounds Addon in Storybook: Configuration, Defaults, and Customization

The Backgrounds addon in Storybook lets you switch background colors and toggle a configurable grid overlay via a toolbar button, configured through parameters.backgrounds in .storybook/preview.js or per-story overrides.

The backgrounds addon is a core part of Storybook’s Essentials collection, providing instant visual context switching for your components. According to the storybookjs/storybook source code, this addon operates through a coordinated manager UI and preview decorator system that injects CSS dynamically. Whether you need to test components against dark mode or verify alignment with a grid, the addon requires minimal configuration while offering deep customization through its parameter-based API.

How the Backgrounds Addon Works

The implementation is split between two runtime layers that communicate via Storybook’s addon channel.

Manager UI Layer

The manager UI registers a toolbar button that opens the background picker. In code/core/src/backgrounds/manager.tsx, the registration only occurs when globalThis.FEATURES.backgrounds is enabled. The addons.register(ADDON_ID, ...) call adds a TOOL type entry whose render method displays the BackgroundTool React component from code/core/src/backgrounds/components/Tool.tsx.

Preview Decorator Layer

The preview decorator handles the actual CSS injection. The withBackgroundAndGrid decorator in code/core/src/backgrounds/decorator.ts runs for every story. It reads the current globals (globals[PARAM_KEY]) and story-level parameters (parameters[PARAM_KEY]), then calls addBackgroundStyle and addGridStyle from code/core/src/backgrounds/utils.ts to inject or remove <style> tags targeting .sb-show-main or the Docs container.

Enabling and Configuring the Backgrounds Addon

Enable the Feature Flag

First, ensure the feature is active in your main configuration file. The manager checks globalThis.FEATURES?.backgrounds before registering the toolbar.

// .storybook/main.js
module.exports = {
  // ...other config
  features: {
    backgrounds: true, // Enables the toolbar and decorator
  },
};

Set Global Defaults

Define your color palette and grid settings in preview.js. The BackgroundsParameters interface (defined in code/core/src/backgrounds/types.ts) expects a default key matching one of the options keys, plus optional grid configuration.

// .storybook/preview.js
export const parameters = {
  backgrounds: {
    default: 'light',
    grid: {
      cellSize: 20,
      cellAmount: 8,
      opacity: 0.6,
    },
    options: {
      light: { name: 'light', value: '#ffffff' },
      dark:  { name: 'dark',  value: '#222222' },
      sky:   { name: 'sky',   value: '#87CEEB' },
    },
  },
};

The built-in defaults from code/core/src/backgrounds/defaults.ts provide "light" (#F8F8F8) and "dark" (#333333) if you do not override them.

Override Per-Story Backgrounds

You can override the global default for individual stories or components using the parameters key in your story file.

// src/components/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  title: 'Example/Button',
  parameters: {
    backgrounds: {
      default: 'dark', // Overrides global default for this component
    },
  },
};

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

export const Primary: Story = {
  args: { label: 'Primary' },
};

export const WithSkyBackground: Story = {
  args: { label: 'Sky' },
  parameters: {
    backgrounds: {
      default: 'sky',
      grid: { cellSize: 40, opacity: 0.4 }, // Custom grid for this story only
    },
  },
};

Programmatic Control with useGlobals

For advanced use cases, you can manipulate the background state programmatically using the useGlobals hook from @storybook/addons. This updates the same global state that the withBackgroundAndGrid decorator consumes, triggering immediate CSS updates via the utilities in code/core/src/backgrounds/utils.ts.

import { useGlobals } from '@storybook/addons';

export const DynamicBackground = () => {
  const [{ backgrounds }, updateGlobals] = useGlobals();

  const toggle = () => {
    const next = backgrounds?.value === '#F8F8F8' ? '#333' : '#F8F8F8';
    updateGlobals({ backgrounds: { value: next } });
  };

  return <button onClick={toggle}>Toggle background</button>;
};

Key Source Files and Architecture

Understanding the source structure helps with debugging and customization:

File	Purpose	Key Exports
code/core/src/backgrounds/manager.tsx	Registers the toolbar UI button	addons.register(ADDON_ID, ...)
code/core/src/backgrounds/decorator.ts	Injects CSS into the preview iframe	withBackgroundAndGrid
code/core/src/backgrounds/constants.ts	Addon identifiers	ADDON_ID, PARAM_KEY
code/core/src/backgrounds/types.ts	TypeScript interfaces	BackgroundsParameters, Background
code/core/src/backgrounds/defaults.ts	Built-in color presets	Default light/dark maps
code/core/src/backgrounds/utils.ts	DOM manipulation helpers	addBackgroundStyle, addGridStyle
code/core/src/backgrounds/components/Tool.tsx	React toolbar component	BackgroundTool

Summary

• Enable the feature by setting features: { backgrounds: true } in .storybook/main.js so the manager registers the toolbar.
• Configure globally in .storybook/preview.js using parameters.backgrounds to set default colors, grid options, and the color palette.
• Override per-story by setting parameters.backgrounds in your Meta object or individual story exports.
• Understand the architecture: The manager UI (manager.tsx) handles the toolbar, while the preview decorator (decorator.ts) injects CSS using utilities from utils.ts.

Frequently Asked Questions

How do I disable the backgrounds addon for a specific story?

Set the backgrounds parameter to false or an empty object in the story’s parameters. The withBackgroundAndGrid decorator in code/core/src/backgrounds/decorator.ts checks for the existence of the parameter before applying styles.

export const NoBackground: Story = {
  parameters: {
    backgrounds: { disable: true },
  },
};

Can I use background images instead of solid colors?

Yes. The value property in the BackgroundsParameters options accepts any valid CSS background value, including url() gradients or image paths. The addBackgroundStyle function in code/core/src/backgrounds/utils.ts injects the value directly into the CSS background property.

parameters: {
  backgrounds: {
    options: {
      pattern: { name: 'Pattern', value: 'url(/bg.png)' },
    },
  },
}

Why isn't the backgrounds toolbar showing up?

The toolbar only registers when globalThis.FEATURES.backgrounds is true. Verify that you have enabled the feature flag in .storybook/main.js and that you are using a Storybook version that includes the Essentials addon (v6.0+). Check the browser console for addon registration errors.

How do I change the default grid size globally?

Configure the grid object inside parameters.backgrounds in .storybook/preview.js. The grid property accepts cellSize (in pixels), cellAmount (number of cells), and opacity (0-1), which the decorator passes to addGridStyle in code/core/src/backgrounds/utils.ts.

parameters: {
  backgrounds: {
    grid: {
      cellSize: 16,
      cellAmount: 4,
      opacity: 0.5,
    },
  },
}

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}