storybook/docs/src/pages/basics/writing-stories/index.md

id	title
writing-stories	Writing Stories

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

Technically, a story is a function that returns something that can be rendered to screen.

Basic story

Here is a simple example of stories for a Button component:

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

export default { title: 'Button' };

export const withText = () => <Button onClick={action('clicked')}>Hello Button</Button>;

export const withEmoji = () => (
  <Button onClick={action('clicked')}>
    <span role="img" aria-label="so cool">
      😀 😎 👍 💯
    </span>
  </Button>
);

This is what you'll see in Storybook:

The named exports define the Button's stories, and the default export defines metadata that applies to the group. In this case, the title determines the title of the group in Storybook's left-hand navigation panel.

This example is written in Storybook's Module format. Storybook also supports:

• a classic storiesOf format, which adds stories through Storybook's API.
• an experimental MDX format, which mixes longform Markdown docs and JSX stories.

Since Module format is a new additon to Storybook, most Storybook examples you'll find in the wild are written in the legacy storiesOf format.

Furthermore, Storybook for React Native currently only supports the storiesOf format. React Native will get Module and MDX support in a future release.

Story file location

Stories are easier to maintain when they are located alongside the components they are documented. We recommend:

•
└── src
    └── components
        └── button
            ├── button.js
            └── button.stories.js

It's up to you to find a naming/placing scheme that works for your project/team. Other naming conventions:

stories sub-directory in component directory

•
└── src
    └── components
        └── button
            ├── button.js
            └── stories
                └── button.stories.js

stories directory outside src directory

•
├── src
│   └── components
│       └── button.js
└── stories
    └── button.stories.js

Loading stories

Stories are loaded in the .storybook/config.js file.

The most convenient way to load stories is by filename. For example, if you stories files are located in the src/components directory, you can use the following snippet.

import { load } from '@storybook/react';

load(require.context('../src/components', true, /\.stories\.js$/), module);

The load function may be called multiple times to load stories from different locations.

Storybook uses Webpack's require.context to load modules dynamically. Take a look at the relevant Webpack docs to learn more about how to use require.context.

The load function is available since Storybook 5.2 and is the recommended way to load stories. It replaces the configure function, which is still in use in most Storybook examples, and is the only way to currently load stories in React Native.

Decorators

A decorator is a way to wrap a story with a common set of components, for example if you want to wrap a story in some formatting, or provide some context to the story.

Decorators can be applied globally, at the component level, or individually at the story level. Global decorators are typically applied in the Storybook config files, and component/story decorators are applied in the story file.

Here is an example of a global decorator which centers every story in the storybook:

import React from 'react';
import { load, addDecorator } from '@storybook/react';

addDecorator(storyFn => <div style={{ textAlign: 'center' }}>{storyFn()}</div>);

load(require.context('../src/components', true, /\.stories\.js$/), module);

And here's an example of component/local decorators. The component decorator wraps all the stories in a yellow frame, and the story director wraps a single story in an additional red frame.

import React from 'react';
import MyComponent from './MyComponent';

export default {
  title: 'MyComponent',
  decorators: [storyFn => <div style={{ backgroundColor: 'yellow' }}>{storyFn()}</div>],
};

export const normal = () => <MyComponent />;
export const special = () => <MyComponent text="The Boss" />;
special.story = {
  decorators: [storyFn => <div style={{ border: '5px solid red' }}>{storyFn()}</div>],
};

Decorators are not just for story formatting, they are generally useful for any kind of context needed by a story.

• Theming libraries require a theme to be passed in through context. Rather than redefining this in every story, just add a decorator.
• Likewise, state management libraries like Redux provide a global data store through context.
• Finally, Storybook addons heavily use decorators. For example, the Storybook's Knobs addon uses decorators to modify the input properties of the story based on a UI.

Parameters

Parameters are custom metadata for a story. Like decorators, they can also be hierarchically applied: globally, at the component level, or locally at the story level.

Here's an example where we are annotating our stories with Markdown notes using parameters, to be displayed in the Notes addon.

We first apply some notes globally in the Storybook config.

import { load, addParameters } from '@storybook/react';
import defaultNotes from './instructions.md';
addParameters({ notes: defaultNotes });

This would make sense if, for example, instructions.md contained instructions on how to document your components when there is no documentation available.

Then for componenents that did have documentation, we might override it at the component/story level:

import React from 'react';
import MyComponent from './MyComponent';
import componentNotes from './notes.md';
import specialNotes from '/.special.md';

export default {
  title: 'MyComponent',
  parameters: { notes: componentNotes },
};

export const small = () => <MyComponent text="small" />;
export const medium = () => <MyComponent text="medium" />;
export const special = () => <MyComponent text="The Boss" />;
special.story = {
  notes: specialNotes,
};

In this example, the small and medium stories get the compoonent notes documented in notes.md (as opposed to the generic instructions in instructions.md). The special story gets some special notes.

Searching

By default, search results will show up based on the file name of your stories. As of storybook 5, you can extend this with notes to have certain stories show up when the search input contains matches. For example, if you built a Callout component that you want to be found by searching for popover or tooltip as well, you could use notes like this:

.add(
  "Callout",
  () => (
    <Callout>Some children</Callout>
  ),
  {
    notes: "popover tooltip"
  }
)

Story hierarchy

Stories can be organized in a nested structure using "/" as a separator, and can be given a top-level heading using a "|" root separator.

For example the following snippets nest the Button and Checkbox components within the Atoms group, under a top-level heading called Design System.

// Button.stories.js
import React from 'react';
import Button from './Button';

export default {
  title: 'Design System|Atoms/Button',
};
export const normal = () => <Button onClick={action('clicked')}>Hello Button</Button>;

// Checkbox.stories.js
import React from 'react';
import Checkbox from './Checkbox';

export default {
  title: 'Design System|Atoms/Checkgox',
};
export const empty = () => <Checkbox label="empty" />;
export const checked = () => <Checkbox label="checked" checked />;

If you prefer other characters as separators, you can configure this using the hierarchySeparator and hierarchyRootSeparator config options. See the configuration options parameter page to learn more.

Generating nesting path based on __dirname

Nesting paths can be programmatically generated with template literals because story names are strings.

One example would be to use base from paths.macro:

import React from 'react';
import base from 'paths.macro';

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

import BaseButton from '../components/BaseButton';

storiesOf(`Other|${base}/Dirname Example`, module)
  .add('story 1', () => <BaseButton label="Story 1" />)
  .add('story 2', () => <BaseButton label="Story 2" />);

This uses babel-plugin-macros.

Run multiple storybooks

Multiple storybooks can be built for different kinds of stories or components in a single repository by specifying different port numbers in the start scripts:

{
  "scripts": {
    "start-storybook-for-theme": "start-storybook -p 9001 -c .storybook-theme",
    "start-storybook-for-app": "start-storybook -p 8001 -c .storybook-app"
  }
}