Component Story Format (CSF)

CSF 4 is the next evolution of Storybook's Component Story Format (CSF). This API uses a pattern called factory functions to provide full type safety to your Storybook stories, making it easier to configure addons correctly and unlocking the full potential of Storybook's features.

You can upgrade your stories to CSF 4 either automatically (from CSF 3) or manually (from CSF 1, 2, or 3). CSF 4 is designed to be usable incrementally; you do not have to upgrade all of your story files at once. However, you cannot mix story formats within the same file.

Before proceeding, be sure you're using the latest version of Storybook. You can upgrade your Storybook automatically with this command:

npx storybook@latest upgrade

Automatically

You can automatically upgrade all of your project's stories from CSF 3 to CSF 4 with this command:

npx storybook automigrate csf-factories

Monorepos

If your project has multiple Storybook configurations, run the command with the --config-dir flag pointing to each config directory:

npx storybook automigrate csf-factories --config-dir apps/admin/.storybook
npx storybook automigrate csf-factories --config-dir apps/website/.storybook

It will run through each of the manual upgrade steps below on all of your story files.

npx storybook migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx

Manual

You can also upgrade your project's story files to CSF 4 manually. Before using CSF 4 in a story file, you must upgrade your .storybook/main.* and .storybook/preview.* files.

1. Update your main Storybook config file

Update your .storybook/main.* file to use the new defineMain function.

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+ import { defineMain } from '@storybook/your-framework/node';
- import { StorybookConfig } from '@storybook/your-framework';
 
+ export default defineMain({
- export const config: StorybookConfig = {
    // ...config itself is unchanged
+ });
- };
- export default config;

2. Update your preview config file

Update your .storybook/preview.* file to use the new definePreview function.

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+ import { definePreview } from '@storybook/your-framework';
- import type { Preview } from '@storybook/your-framework';
// 👇 Import the addons you are using
+ import addonA11y from '@storybook/addon-a11y';
 
+ export default definePreview({
- export const preview: Preview = {
    // ...current config
    // 👇 Add your addons here
+   addons: [addonA11y()],
+ });
- };
- export default preview;

3. Update your story files

Story files have been updated for improved usability. With the new format:

• Import the preview construct from the Storybook preview file
• The meta object is now created via the preview.meta function and does not have to be exported as a default export
• Stories are now created from the meta object, via the meta.story function

+ import preview from '../.storybook/preview';
- import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
+ const meta = preview.meta({
- const meta = {
    // ...meta object is unchanged
+ });
- } satisfies Meta<typeof Button>;
- export default meta;
 
- type Story = StoryObj<typeof meta>;
 
+ export const Primary = meta.story({
- export const Primary: Story = {
    // ...story object is unchanged
+ });
- };

Note that importing or manually applying the component props type to the meta or stories is no longer necessary. Thanks to the factory function pattern, the types are now inferred automatically.

+ import preview from '../.storybook/preview';
- import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
type CustomProps = React.ComponentProps<typeof Button> & { customProp: string };
 
+ const meta = preview.type<{ args: CustomProps }>().meta({
- const meta = {
    // ...meta object is unchanged
+ });
- } satisfies Meta<CustomProps>;
- export default meta;
 
- type Story = StoryObj<typeof meta>;
 
+ export const Primary = meta.story({
- export const Primary: Story = {
    // ...story object is unchanged
+ });
- };

+ const meta = preview.meta({
- const meta = {
    component: Button,
+ });
- } satisfies Meta<typeof Button>;
- export default meta;
 
+ export const WithCustomProp = meta.type<{ args: { customProp: string } }>().story({
- export const WithCustomProp: StoryObj<CustomProps> = {
    args: { customProp: 'Hello, world!' },
+ });
- };

- import { fn } from 'storybook/test';
+ import { fn, mocked } from 'storybook/test';
 
  beforeEach: async ({ args }) => {
-   args.getUsers.mockResolvedValue(users);
+   mocked(args.getUsers).mockResolvedValue(users);
  },

3.1 Reusing story properties

Previously, story properties such as Story.args or Story.parameters were accessed directly when reusing them in another story. While accessing them like this is still supported, it is deprecated in CSF 4.

All of the story properties are now contained within a new property called composed and should be accessed from that property instead. For instance, Story.composed.args or Story.composed.parameters.

// ...rest of file
 
+ export const Primary = meta.story({
- export const Primary: Story = {
    args: { primary: true },
+ });
- };
 
+ export const PrimaryDisabled = meta.story({
- export const PrimaryDisabled: Story = {
    args: {
+     ...Primary.composed.args,
-     ...Primary.args,
      disabled: true,
    }
+ });
- };

4. Update your Vitest setup file

If you're using Storybook's Vitest addon, you no longer need a Vitest setup file (.storybook/vitest.setup.ts) and must remove it.

If you are using portable stories in Vitest, you may use a Vitest setup file to configure your stories. This file must be updated to use the new CSF 4 format.

5. Reusing stories in test files

Storybook's Vitest addon allows you to test your components directly inside Storybook. All the stories are automatically turned into Vitest tests, making integration seamless in your testing suite.

If you cannot use Storybook Test, you can still reuse the stories in your test files using portable stories. In prior story formats, you had to compose the stories before rendering them in your test files. With CSF 4, you can now reuse the stories directly.

import { test, expect } from 'vitest';
import { screen } from '@testing-library/react';
- import { composeStories } from '@storybook/your-framework';
 
// Import all stories from the stories file
import * as stories from './Button.stories';
 
+ const { Primary } = stories;
- const { Primary } = composeStories(stories);
 
test('renders primary button with default args', async () => {
  // The run function will mount the component and run all of Storybook's lifecycle hooks
  await Primary.run();
  const buttonElement = screen.getByText('Text coming from args in stories file!');
  expect(buttonElement).not.toBeNull();
});

The Story object also provides a Component property, enabling you to render the component with any method you choose, such as Testing Library. You can also access its composed properties (args, parameters, etc.) via the composed property.

Here's an example of how you can reuse a story in a test file by rendering its component:

import { test, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
 
// Import all stories from the stories file
import * as stories from './Button.stories';
 
const { Primary, Secondary } = stories;
 
test('renders primary button with default args', async () => {
  // Access the story's component via the .Component property
  render(<Primary.Component />);
  const buttonElement = screen.getByText('Text coming from args in stories file!');
  expect(buttonElement).not.toBeNull();
});
 
test('renders primary button with overridden props', async () => {
  // You can override props by passing them directly to the story's component
  render(<Primary.Component>Hello world</Primary.Component>);
  const buttonElement = screen.getByText(/Hello world/i);
  expect(buttonElement).not.toBeNull();
});