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.js

export const parameters = {
  backgrounds: {
    default: 'twitter',
    values: [
      {
        name: 'twitter',
        value: '#00aced',
      },
      {
        name: 'facebook',
        value: '#3b5998',
      },
    ],
  },
};

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.js|jsx|ts|tsx

import { Button } from './Button';
 
// To apply a set of backgrounds to all stories of Button:
export default {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/6/configure#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
  parameters: {
    backgrounds: {
      default: 'twitter',
      values: [
        { name: 'twitter', value: '#00aced' },
        { name: 'facebook', value: '#3b5998' },
      ],
    },
  },
};

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.js|jsx|ts|tsx

import { Button } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
};
 
const Template = (args) => ({
  //👇 Your template goes here
});
 
export const Large = Template.bind({});
Large.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.js|jsx|ts|tsx

import { Button } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
};
 
const Template = (args) => ({
  //👇 Your template goes here
});
 
export const Large = Template.bind({});
Large.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.js|jsx|ts|tsx

import { Button } from './Button';
 
// To apply a grid to all stories of Button:
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: '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'
      },
    },
  },
};

Disable the grid

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

Button.stories.js|jsx|ts|tsx

import { Button } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
};
 
const Template = (args) => ({
  //👇 Your template goes here
});
 
export const Large = Template.bind({});
Large.parameters = {
  backgrounds: {
    grid: {
      disable: true,
    }
  }
};