@storybook/addon-backgrounds

What is @storybook/addon-backgrounds?

The @storybook/addon-backgrounds package is a Storybook addon that allows developers to switch between different backgrounds for their components' preview in the Storybook UI. It is useful for visualizing how components look against different backgrounds and can be used to simulate different environments.

What are @storybook/addon-backgrounds's main functionalities?

Setting default backgrounds

This feature allows you to set default backgrounds that will be available for all stories. You can specify a default background that will be pre-selected when a story is loaded.

import { addParameters } from '@storybook/react';
addParameters({
  backgrounds: [
    { name: 'twitter', value: '#00aced', default: true },
    { name: 'facebook', value: '#3b5998' },
  ],
});

Configuring backgrounds for individual stories

This feature allows you to configure backgrounds for individual stories. You can override the default backgrounds for specific stories to tailor the background to the component's needs.

import { storiesOf } from '@storybook/react';
storiesOf('Button', module)
  .addParameters({
    backgrounds: [
      { name: 'dark', value: '#222222' },
      { name: 'light', value: '#eeeeee' },
    ],
  })
  .add('with text', () => <button>Click me</button>);

Other packages similar to @storybook/addon-backgrounds

@storybook/addon-knobs

The @storybook/addon-knobs package allows you to edit React props dynamically using the Storybook UI. It is similar to @storybook/addon-backgrounds in that it enhances the Storybook experience by allowing for real-time changes to the component's environment, but it focuses on props rather than backgrounds.

@storybook/addon-actions

The @storybook/addon-actions package can be used to display data received by event handlers in Storybook. It is similar to @storybook/addon-backgrounds in that it helps in visualizing and debugging components, but it focuses on capturing and displaying actions rather than changing backgrounds.

@storybook/addon-viewport

The @storybook/addon-viewport package allows you to adjust the viewport size and layout for responsive design testing within Storybook. While @storybook/addon-backgrounds changes the background behind components, @storybook/addon-viewport changes the size of the frame that the component is rendered within.

README

Storybook Addon Backgrounds

Storybook Background Addon can be used to change background colors inside the preview in Storybook.

Framework Support

Installation

npm i -D @storybook/addon-backgrounds

Configuration

Then create a file called addons.js in your storybook config.

Add following content to it:

import '@storybook/addon-backgrounds/register';

Usage

Then write your stories like this:

import React from 'react';
import { storiesOf } from '@storybook/react';
import { withBackgrounds } from '@storybook/addon-backgrounds';

storiesOf('Button', module)
  .addDecorator(
    withBackgrounds([
      { name: 'twitter', value: '#00aced', default: true },
      { name: 'facebook', value: '#3b5998' },
    ])
  )
  .add('with text', () => <button>Click me</button>);

You can add the backgrounds to all stories with addDecorator in .storybook/config.js:

import { addDecorator } from '@storybook/react'; // <- or your storybook framework
import { withBackgrounds } from '@storybook/addon-backgrounds';

addDecorator(
  withBackgrounds([
    { name: 'twitter', value: '#00aced', default: true },
    { name: 'facebook', value: '#3b5998' },
  ])
);

If you want to override backgrounds for a single story or group of stories, pass the backgrounds parameter:

import React from 'react';
import { storiesOf } from '@storybook/react';

storiesOf('Button', module)
  .addParameters({
    backgrounds: [
      { name: 'red', value: '#F44336' },
      { name: 'blue', value: '#2196F3', default: true },
    ],
  })
  .add('with text', () => <button>Click me</button>);

If you don't want to use backgrounds for a story, you can set the backgrounds parameter to [], or use { disable: true } to skip the addon:

import React from 'react';
import { storiesOf } from '@storybook/react';

storiesOf('Button', module).add('with text', () => <button>Click me</button>, {
  backgrounds: { disable: true },
});

You can choose your background in a running storybook instance with the background query param and either set the background value or the name as the parameter value. E.g. ?background=twitter or ?background=#00aced.