Storybook - Story Writing

Write well-structured, maintainable Storybook stories using Component Story Format 3 (CSF3) that showcase component variations and ensure consistent rendering.

Key Concepts

Component Story Format 3 (CSF3)

CSF3 is the modern Storybook format that uses object syntax for stories:

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    label: 'Button',
  },
};

Story Organization

• One story file per component: Component.stories.tsx
• Use descriptive story names: Primary, Secondary, Large, Disabled
• Group related stories under a title hierarchy: Components/Forms/Input

Default Export (Meta)

The default export defines metadata for all stories:

const meta = {
  title: 'Components/Button',        // Navigation path
  component: Button,                  // Component reference
  parameters: {},                     // Story-level config
  tags: ['autodocs'],                // Enable auto-documentation
  argTypes: {},                       // Control types
  decorators: [],                     // Wrappers for stories
} satisfies Meta<typeof Button>;

Best Practices

1. Use TypeScript for Type Safety

import type { Meta, StoryObj } from '@storybook/react';

const meta = {
  component: Button,
} satisfies Meta<typeof Button>;

type Story = StoryObj<typeof meta>;

2. Show All Component States

Create stories for each meaningful state:

export const Default: Story = {
  args: {
    label: 'Click me',
  },
};

export const Loading: Story = {
  args: {
    label: 'Loading...',
    loading: true,
  },
};

export const Disabled: Story = {
  args: {
    label: 'Disabled',
    disabled: true,
  },
};

export const WithIcon: Story = {
  args: {
    label: 'Download',
    icon: 'download',
  },
};

3. Use Sensible Defaults

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
    size: 'medium',
  },
};

// Extend existing stories
export const PrimaryLarge: Story = {
  ...Primary,
  args: {
    ...Primary.args,
    size: 'large',
  },
};

4. Add Descriptive Parameters

export const WithTooltip: Story = {
  args: {
    label: 'Hover me',
    tooltip: 'Click to submit',
  },
  parameters: {
    docs: {
      description: {
        story: 'Shows a tooltip on hover to provide additional context.',
      },
    },
  },
};

5. Use Decorators for Context

import { RouterDecorator } from '../decorators';

const meta = {
  component: Navigation,
  decorators: [
    (Story) => (
      <div style={{ padding: '3rem' }}>
        <Story />
      </div>
    ),
    RouterDecorator,
  ],
} satisfies Meta<typeof Navigation>;

Common Patterns

Form Components

export const EmptyForm: Story = {
  args: {
    onSubmit: (data) => console.log(data),
  },
};

export const PrefilledForm: Story = {
  args: {
    defaultValues: {
      email: '[email protected]',
      name: 'John Doe',
    },
  },
};

export const WithValidationErrors: Story = {
  args: {
    errors: {
      email: 'Invalid email format',
      name: 'Name is required',
    },
  },
};

Layout Components

export const WithSidebar: Story = {
  args: {
    sidebar: <Sidebar ite