| title |
|---|
Naming components and hierarchy |
The title of the component you export in the default export controls the name shown in the sidebar.
<CodeSnippets paths={[ 'angular/button-story-default-export.ts.mdx', 'web-components/button-story-default-export.js.mdx', 'web-components/button-story-default-export.ts.mdx', 'common/button-story-default-export.js.mdx', 'common/button-story-default-export.ts.mdx', ]} usesCsf3 csf2Path="writing-stories/naming-components-and-hierarchy#snippet-button-story-default-export" />
Yields this:
It is also possible to group related components in an expandable interface to help with Storybook organization. To do so, use the / as a separator:
<CodeSnippets paths={[ 'angular/button-story-grouped.ts.mdx', 'web-components/button-story-grouped.js.mdx', 'web-components/button-story-grouped.ts.mdx', 'common/button-story-grouped.js.mdx', 'common/button-story-grouped.ts.mdx', ]} usesCsf3 csf2Path="writing-stories/naming-components-and-hierarchy#snippet-button-story-grouped" />
<CodeSnippets paths={[ 'angular/checkbox-story-grouped.ts.mdx', 'web-components/checkbox-story-grouped.js.mdx', 'web-components/checkbox-story-grouped.ts.mdx', 'common/checkbox-story-grouped.js.mdx', 'common/checkbox-story-grouped.ts.mdx', ]} usesCsf3 csf2Path="writing-stories/naming-components-and-hierarchy#snippet-checkbox-story-grouped" />
Yields this:
By default, the top-level grouping will be displayed as “root” in the Storybook UI (i.e., the uppercased, non-expandable items). If you need, you can configure Storybook and disable this behavior. Useful if you need to provide a streamlined experience for your users; nevertheless, if you have a large Storybook composed of multiple component stories, we recommend naming your components according to the file hierarchy.
Single-story components (i.e., component stories without siblings) whose display name exactly matches the component's name (last part of title) are automatically hoisted up to replace their parent component in the UI. For example:
<CodeSnippets paths={[ 'angular/button-story-hoisted.ts.mdx', 'web-components/button-story-hoisted.js.mdx', 'web-components/button-story-hoisted.ts.mdx', 'common/button-story-hoisted.js.mdx', 'common/button-story-hoisted.ts.mdx', ]} usesCsf3 csf2Path="writing-stories/naming-components-and-hierarchy#snippet-button-story-hoisted" />
Because story exports are automatically "start cased" (myStory becomes "My Story"), your component name should match that. Alternatively, you can override the story name using myStory.storyName = '...' to match the component name.
Out of the box, Storybook sorts stories based on the order in which they are imported. However, you can customize this pattern to suit your needs and provide a more intuitive experience by adding storySort to the options parameter in your preview.js file.
<CodeSnippets paths={[ 'common/storybook-preview-sort-function.js.mdx', 'common/storybook-preview-sort-function.ts.mdx', ]} />
ℹ️ Asides from the unique story identifier, you can also use the title, name, and import path to sort your stories using the storySort function.
The storySort can also accept a configuration object.
<CodeSnippets paths={[ 'common/storybook-preview-empty-sort-object.js.mdx', 'common/storybook-preview-empty-sort-object.ts.mdx', ]} />
| Field | Type | Description | Required | Default Value | Example |
|---|---|---|---|---|---|
| method | String | Tells Storybook in which order the stories are displayed | No | Storybook configuration | 'alphabetical' |
| order | Array | The stories to be shown, ordered by supplied name | No | Empty Array [] |
['Intro', 'Components'] |
| includeName | Boolean | Include story name in sort calculation | No | false |
true |
| locales | String | The locale required to be displayed | No | System locale | en-US |
To sort your stories alphabetically, set method to 'alphabetical' and optionally set the locales string. To sort your stories using a custom list, use the order array; stories that don't match an item in the order list will appear after the items in the list.
The order array can accept a nested array to sort 2nd-level story kinds. For example:
<CodeSnippets paths={[ 'common/storybook-preview-with-ordered-pages.js.mdx', 'common/storybook-preview-with-ordered-pages.ts.mdx', ]} />
Which would result in this story ordering:
Introand thenIntro/*storiesPagesstoryPages/HomeandPages/Home/*storiesPages/LoginandPages/Login/*storiesPages/AdminandPages/Admin/*storiesPages/*storiesComponentsandComponents/*stories- All other stories
If you want specific categories to sort to the end of the list, you can insert a * into your order array to indicate where "all other stories" should go:
<CodeSnippets paths={[ 'common/storybook-preview-with-ordered-pages-and-wildcard.js.mdx', 'common/storybook-preview-with-ordered-pages-and-wildcard.ts.mdx', ]} />
In this example, the WIP category would be displayed at the end of the list.
Note that the order option is independent of the method option; stories are sorted first by the order array and then by either the method: 'alphabetical' or the default configure() import order.