Backgrounds

The backgrounds toolbar addon allows you to set the background color in which the story renders in the UI:

Configuration

By default, the backgrounds toolbar includes a light and dark background.

But you're not restricted to these backgrounds, you can configure your own set of colors with the parameters.backgrounds parameter in your .storybook/preview.js:

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    backgrounds: {
      default: 'twitter',
      values: [
        {
          name: 'twitter',
          value: '#00aced',
        },
        {
          name: 'facebook',
          value: '#3b5998',
        },
      ],
    },
  },
};
 
export default preview;

If you define the default property, the addon will apply it to all stories. Otherwise, it's only listed as an available color.

Extending the configuration

You can also define backgrounds per-component or per-story basis through parameter inheritance:

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
// To apply a set of backgrounds to all stories of Button:
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    backgrounds: {
      default: 'twitter',
      values: [
        { name: 'twitter', value: '#00aced' },
        { name: 'facebook', value: '#3b5998' },
      ],
    },
  },
};
 
export default meta;

You can also override a single key on the backgrounds parameter, for instance, to set a different default value for a particular story:

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Large: Story = {
  parameters: {
    backgrounds: { default: 'facebook' },
  },
};

Disable backgrounds

If you want to disable backgrounds in a story, you can do so by setting the backgrounds parameter like so:

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Large: Story = {
  parameters: {
    backgrounds: { disable: true },
  },
};

Grid

Backgrounds toolbar also includes a Grid selector. This way, you can quickly see if your components are aligned.

You don't need additional configuration to get started. But its properties are fully customizable, if you don't supply any value to any of its properties, they'll default to the following values:

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
// To apply a set of backgrounds to all stories of Button:
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    backgrounds: {
      grid: {
        cellSize: 20,
        opacity: 0.5,
        cellAmount: 5,
        offsetX: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
        offsetY: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
      },
    },
  },
};
 
export default meta;

Disable the grid

If you need to disable the grid for a specific story, set the backgrounds parameter to the following:

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Large: Story = {
  parameters: {
    backgrounds: {
      grid: {
        disable: true,
      },
    },
  },
};

API

Parameters

This addon contributes the following parameters to Storybook, under the backgrounds namespace:

`default`

Type: string

Default background color. Must match the name property of one of the available colors.

`disable`

Type: boolean

Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering addon-essentials. See the essential addon's docs for more information.

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to true at the project level, it could then be re-enabled by setting it to false at the meta (component) or story level.

`grid`

Type:

{
  cellAmount?: number;
  cellSize?: number;
  disable?: boolean;
  offsetX: number;
  offsetY: number;
  opacity?: number;
}

`grid.cellAmount`

Type: number

Default: 5

Specify the size of the minor grid lines.

`grid.cellSize`

Type: number

Default: 20

Specify the size of the major grid lines.

`grid.disable`

Type: boolean

Disable the grid.

`grid.offsetX`

Type: number

Default: 0 if story layout is 'fullscreen'; 16 if story layout is 'padded'

Horizontal offset of the grid.

`grid.offsetY`

Type: number

Default: 0 if story layout is 'fullscreen'; 16 if story layout is 'padded'

Vertical offset of the grid.

`grid.opacity`

Type: number

Default: 0.5

Opacity of the grid lines.

`values`

Type: { name: string; value: string }[]

Available background colors. See above for a usage example.