Multistories

Multistories.md

Multistories mode

storyKindName argument passing to storiesOf may contain symbols to indicate multistory sections.

Multistories mode unlike singlestory displays all stories of the section at preview area. It doesn't affect how it appears at the Stories panel.

Default separator: :.

Example:

storiesOf('Buttons Default:', module);

It will create a multistory group: selecting any story from Buttons Default: will show all containing stories at once.

Note Decorators will be applied separately to each story. If you need to set common decorator for the whole preview page use Preview decorator instead.

Grouping multistory sections allows to union some story sets with different storyKindName into one multistory section. storyKindName should have the same parts before multistories separator.

Example:

storiesOf('Button: Default', module);
storiesOf('Button: Accent', module);

It will create two stories sets with common multistories page. You can access the common and extra part of the storyKindName via decorators. In combination with other context parameters this is a great opportunity to customize your storybook appearance and behaviour (see advanced stories organization link guide for details).

Multistories with hierarchy: Applying multistories mode over the common hierarchy levels provides good story organization experience.

Example:

storiesOf('Widgets/Button:/Default', module);
storiesOf('Widgets/Button:/Accent', module);
storiesOf('Widgets/Button:/Disabled', module);

It'll create nested stories structure with all Widgets/Buttons stories in one preview page divided into three groups of Default, Accent and Disabled sections.

You can set your own multistories separator passing multistorySeparator option via setOption API:

setOptions({
  multistorySeparator: /#/,
});

• multistorySeparator [string] or [regular expression]

If you pass string it should contain body of regular expression. Note: In case of string don't forget to escape regexp characters, so the /\// regexp becomes a '\\/' string.

.addDecorator

Adds a stories decorator to a stories object.

Syntax:

stories = stories.addDecorator(function decoratorFn(storyfn, context) { /* Return a decorator */ })

• decoratorFn [function] a decorator function. Should return a valid React Component. Taking two arguments:

• • storyfn - a current function with a decorated story.
• • context - an object with information about specified story and storiesObject. Containing fields:
• • • kind - current storyKindName
• • • story - current storyName
• • • kindRoot - part of storyKindName before the first multistorySeparator. If there is no multistorySeparator it's same as kind
• • • selectedStory - in multi stories mode the story selected at the Stories Panel. In single stories mode it's same as a story
• • • onStoryDidMount(function storyDidMount(elmentID)) - a function that takes a callback function storyDidMount as an agrument, which will be invoked after all stories will be mounted. storyDidMount will be invoked with an argument:
• • • • elmentID [string] - an ID attribute of <div> node containing the current story

Return value:

• stories The same stories object so you can add stories or another decorators.

Decorators composition:

You can add several decorators to a stories object. They will wrap each other in a nesting way. Note: Next added decorator will wrap the previous ones.

// todo: check the decorators order

Example:

storiesOf('Button', module)
  .addDecorator(innerDecorator())
  .addDecorator(mediumDecorator())
  .addDecorator(rootDecorator())
  .add('with text', () => (
    <Button>Hello Button</Button>
  ))
  .add('with some emoji', () => (
    <Button>😀 😎 👍 💯</Button>
  ));