Storybook for React — Backgrounds and Globals

Storybook lets us prototype components easily with various parameters.

In this article, we’ll look at how to work with globals with Storybook.

Backgrounds

We can set the backgrounds toolbar item to add choices for setting the background.

We can do this globally by adding the options in the .storybook/preview.js file:

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

We set the backgrounds property to set the choices for setting the background color.

values has an array of choices that we can set.

name is the name that’s displayed in the dropdown and value is the background color value.

default is the name of the choice to display.

We can also set the choices for one set of stories.

To do that, we write:

src/stories/Button.stories.js

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  parameters: {
    backgrounds: {
      default: 'twitter',
      values: [
        {
          name: 'twitter',
          value: '#00aced'
        },
        {
          name: 'facebook',
          value: '#3b5998'
        },
      ],
    }
  }
};

We set the background color in the Button stories set within the parameters property.

Also, we can set the background color dropdown only for one story.

To do that, we write:

src/stories/Button.stories.js

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

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

The backgrounds can also be disabled with the disable property set to true :

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

Primary.parameters = {
  backgrounds: { disable: true }
};

We disable the background dropdown with the Primary story.

Toolbars and Globals

We can create our own Storybook toolbar items to control special global variables.

Globals are non-story-specific inputs to the rendering of the story

They aren’t passed into a story as args.

We can add our own toolbar by putting some properties in the .storybook/preview.js file:

export const globalTypes = {
  theme: {
    name: 'Theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
    },
  },
};

We have the theme property with some properties.

The toolbar property has the icon property to set the icon for the dropdown choices.

items has an array of items to choose from.

Create a Decorator

We can consume the theme global with a decorator.

For example, we can write:

.storybook/preview.js

import React from 'react';
import { ThemeProvider } from 'styled-components';

export const globalTypes = {
  theme: {
    name: 'Theme',
    description: 'Global theme for components',
    defaultValue: 'palevioletred',
    toolbar: {
      icon: 'circlehollow',
      items: ['palevioletred', 'white'],
    },
  },
};

const withThemeProvider = (Story, context) => {
  return (
    <ThemeProvider theme={{ main: context.globals.theme }}>
      <Story {...context} />
    </ThemeProvider>
  )
}
export const decorators = [withThemeProvider];

We added some theme choices with the toolbar property.

And we get the selected value with the context.globals.theme property.

We wrapped the ThemeProvider around our Story component, which is whatever component we display in the story.

And then we export the withThemeProvider we created which we put in an array.

Now we can set the theme by selecting it from the dropdown.

Conclusion

We can add choices for backgrounds and set globals which we use with decorators.