storybook/lib/core/docs/storiesOf.md

storiesOf (Legacy) API

storiesOf is Storybook's Legacy API for adding stories. Up until Storybook 5.2, it has been the primary way to create stories in Storybook.

In Storybook 5.2 we introduced a simpler and more portable Component Story Format, and all future tools and infrastructure will be oriented towards CSF. Therefore, we recommend migrating your stories out of storiesOf API, and even provide automated tools to do this.

That said, the storiesOf API is not officially deprecated. For the time being we plan to support it for the foreseeable future.

storiesOf API

A Storybook is a collection of stories. Each story represents a single visual state of a component.

Here's a basic story file in the storiesOf API:

import React from 'react';
import { storiesOf } from '@storybook/react';
import { action } from '@storybook/addon-actions';
import Button from '../components/Button';

storiesOf('Button', module)
  .add('with text', () => <Button onClick={action('clicked')}>Hello Button</Button>)
  .add('with some emoji', () => (
    <Button onClick={action('clicked')}>
      <span role="img" aria-label="so cool">
        😀 😎 👍 💯
      </span>
    </Button>
  ));

The string argument to storiesOf is the component title. If you pass a string like 'Widgets|Button/Button' it can also be used to position your component's story within Storybook's story hierarchy.

The second argument to storiesOf is the module object, the one you might be familiar with from ES5's module.exports. Storybook needs a reference to the file/module where your story lives to enable hot-module-replacement. If you do not supply it, you'd need to refresh your browser for every change you make.

Each .add call takes a story name, a story function that returns a renderable object (JSX in the case of React), and optionally some parameters, which are described below.

Decorators and parameters

Decorators and parameters can be specified globally, at the component level, or locally at the story level.

In the storiesOf API, story-level parameters are provided as a third argument to .add:

storiesOf('Button', module).add(
  'with text',
  () => <Button onClick={action('clicked')}>Hello Button</Button>,
  { notes: someNotes }
);

Story-level decorators are provided via parameters:

storiesOf('Button', module).add(
  'with text',
  () => <Button onClick={action('clicked')}>Hello Button</Button>,
  { decorators: [withKnobs] }
);

We can set the parameters and decorators for all stories of a component using the .addParameters and .addDecorator methods. Note that only one .addParameters call is needed, where .addDecorator needs to be called once for every decorator you add.

storiesOf('Button', module)
  .addParameters({backgrounds: {values: [{name: "red" value: "#f00"}]}})
  .addDecorator((Story) => <div style={{ margin: '3em' }}><Story/></div>)
  .addDecorator((Story) => <div style={{ height: '600px' }}><Story/></div>)
  .add('with text', () => <Button onClick={action('clicked')}>Hello Button</Button>)
  .add('with some emoji', () => (
    <Button onClick={action('clicked')}>
      <span role="img" aria-label="so cool">
        😀 😎 👍 💯
      </span>
    </Button>
  ));

Finally, global parameters for all stories can be set via the parameters export of your .storybook/previews.js, see this page for an example.

Global decorators for all stories can be set via the decorators export of your .storybook/preview.js, see this page for an example.

Component Story Format migration

To make it easier to adopt the new Component Story Format (CSF), we've created an automatic migration tool to transform storiesOf API to Module format.

sb migrate storiesof-to-csf --glob=src/**/*.stories.js

For more information, see the CLI's Codemod README.