<aside> ℹ️

Storybook Test has launched and the full documentation is available here: https://storybook.js.org/docs/writing-tests

</aside>

Web applications can have hundreds of components, with thousands of total UI states. Storybook helps you capture and test each of those states, but it can make for a long sidebar. Additionally, stories can serve several purposes, for testing, for documentation, or just for development. Not every story serves every purpose, so viewing the right story at the right time is key. For example, you don’t want your test-only stories to clutter up your documentation.

Here’s how we recommend organizing your Storybook to manage this complexity.

Colocation

We recommend placing your stories file next to the component source file in your project. This colocation makes it easy to find the stories for a component. Here are two common approaches that we’ve seen in projects.

All components in one directory:

•
└─ components
   └─ ui
      ├─ Button.tsx
      ├─ Button.stories.ts
      ├─ Calendar.tsx
      ├─ Calendar.stories.ts
      ├─ Header.tsx
      ├─ Header.stories.ts
      ├─ LoginForm.tsx
      ├─ LoginForm.stories.ts
      ├─ Page.tsx
      └─ Page.stories.ts

Each component in its own directory:

•
└─ components
   └─ button
      ├─ Button.tsx
      ├─ Button.stories.ts
      └─ index.ts
   └─ calendar
      ├─ Calendar.tsx
      ├─ Calendar.stories.ts
      └─ index.ts
   └─ header
      ├─ Header.tsx
      ├─ Header.stories.ts
      └─ index.ts
   └─ login-form
      ├─ index.ts
      ├─ LoginForm.tsx
      └─ LoginForm.stories.ts
   └─ page
      ├─ index.ts
      ├─ Page.tsx
      └─ Page.stories.ts

Auto-title

By default, stories are represented in the sidebar in a structure that matches where they are located in your filesystem, relative to the project root. For most projects, this is a good organizational strategy, because it makes it easier to find the story and component being viewed.

A project structure like this:

•
└─ components
   └─ ui
      ├─ Button.tsx
      ├─ Button.stories.ts
      ├─ Calendar.tsx
      ├─ Calendar.stories.ts
      ├─ Header.tsx
      ├─ Header.stories.ts
      ├─ LoginForm.tsx
      ├─ LoginForm.stories.ts
      ├─ Page.tsx
      └─ Page.stories.ts

Becomes a sidebar like this:

If we know that all of a project’s stories are always going to be in the same directory, we can simplify the sidebar presentation by configuring the stories property of Storybook’s main configuration. In the above example, let’s say all stories are in the /components/ui directory and remove those levels from the sidebar by specifying the directory in which to find those stories:

// .storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../components/ui',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
    },
  ],
};

export default config;

That simplifies the sidebar to this:

Title

While we recommend using auto-title as much as possible in your projects, there are situations where a manually defined title is necessary. Simply provide a title property in the meta (default export) of a stories file and Storybook will use that instead. To create (or match) a nested directory structure, use the / separator:

// Button.stories.ts
// Replace your-framework with the framework you are using (e.g., react, vue3)
import type { Meta } from '@storybook/your-renderer';

import { Button } from './Button';

const meta = {
  component: Button,
  // 👇 Provide your own title
  title: 'Folder/sub-folder/World’s best Button',
} satisfies Meta<typeof Button>;

Colocation

Auto-title

Title

Tags