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

> Learn how to use the Storybook backgrounds addon to easily switch background colors and toggle a grid overlay. Configure backgrounds globally or per-story for seamless UI development.

- Repository: [Storybook/storybook](https://github.com/storybookjs/storybook)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`](https://github.com/storybookjs/storybook/blob/main/.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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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.

```javascript
// .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`](https://github.com/storybookjs/storybook/blob/main/preview.js). The `BackgroundsParameters` interface (defined in [`code/core/src/backgrounds/types.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/types.ts)) expects a `default` key matching one of the `options` keys, plus optional `grid` configuration.

```javascript
// .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`](https://github.com/storybookjs/storybook/blob/main/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.

```tsx
// 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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/utils.ts).

```tsx
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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/manager.tsx) | Registers the toolbar UI button | `addons.register(ADDON_ID, ...)` |
| [`code/core/src/backgrounds/decorator.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/decorator.ts) | Injects CSS into the preview iframe | `withBackgroundAndGrid` |
| [`code/core/src/backgrounds/constants.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/constants.ts) | Addon identifiers | `ADDON_ID`, `PARAM_KEY` |
| [`code/core/src/backgrounds/types.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/types.ts) | TypeScript interfaces | `BackgroundsParameters`, `Background` |
| [`code/core/src/backgrounds/defaults.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/defaults.ts) | Built-in color presets | Default light/dark maps |
| [`code/core/src/backgrounds/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/utils.ts) | DOM manipulation helpers | `addBackgroundStyle`, `addGridStyle` |
| [`code/core/src/backgrounds/components/Tool.tsx`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/components/Tool.tsx) | React toolbar component | `BackgroundTool` |

## Summary

- **Enable the feature** by setting `features: { backgrounds: true }` in [`.storybook/main.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/main.js) so the manager registers the toolbar.
- **Configure globally** in [`.storybook/preview.js`](https://github.com/storybookjs/storybook/blob/main/.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`](https://github.com/storybookjs/storybook/blob/main/manager.tsx)) handles the toolbar, while the preview decorator ([`decorator.ts`](https://github.com/storybookjs/storybook/blob/main/decorator.ts)) injects CSS using utilities from [`utils.ts`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/decorator.ts) checks for the existence of the parameter before applying styles.

```tsx
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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/utils.ts) injects the value directly into the CSS `background` property.

```javascript
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`](https://github.com/storybookjs/storybook/blob/main/.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`](https://github.com/storybookjs/storybook/blob/main/.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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/backgrounds/utils.ts).

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

```