Storybook Guide

The complete reference for Storybook — the UI component workshop used by Netflix, Airbnb, and thousands of teams. Covers CSF3 stories, args, decorators, play functions, addons, and visual regression testing.

What is Storybook?

Storybook is an open-source workshop for building, documenting, and testing UI components in isolation. Instead of navigating through your application to reach a specific component state (say, an error state deep in a form flow), Storybook lets you define every state as a "story" — a named configuration with specific props — and jump directly to any state instantly.

This isolation-first approach transforms how teams build design systems. Designers can review components in every state without a developer running the full app. New developers can explore the component library as living documentation. QA engineers can verify edge-case states that are hard to reproduce in the real application. And with Chromatic or other visual testing tools, every pixel change is caught automatically in CI.

Installation

# Automatic setup (detects your framework)
npx storybook@latest init

# For an existing React + Vite project
npx storybook@latest init --type react

# Run Storybook
npm run storybook          # http://localhost:6006

# Build static Storybook for deployment
npm run build-storybook

# Run interaction tests headlessly
npx test-storybook

Writing Stories: CSF3 Format

Component Story Format 3 (CSF3) is the standard way to write Storybook stories. A story file has one default export (component metadata) and multiple named exports (individual states).

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

// Default export: component metadata
const meta: Meta<typeof Button> = {
  title: 'UI/Button',         // Sidebar navigation path
  component: Button,
  tags: ['autodocs'],          // Auto-generate Docs page
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger'],
    },
    size: { control: 'radio', options: ['sm', 'md', 'lg'] },
  },
};

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

// Named exports: individual stories
export const Primary: Story = {
  args: { label: 'Click me', variant: 'primary', size: 'md' },
};

export const Secondary: Story = {
  args: { label: 'Cancel', variant: 'secondary', size: 'md' },
};

export const Danger: Story = {
  args: { label: 'Delete', variant: 'danger', size: 'md' },
};

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

Decorators: Global Context Providers

// .storybook/preview.tsx — applies to ALL stories
import { ThemeProvider } from '../src/theme';
import type { Preview } from '@storybook/react';

const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider theme="light">
        <div style={{ padding: '1rem' }}>
          <Story />
        </div>
      </ThemeProvider>
    ),
  ],
  parameters: {
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#1a1a1a' },
      ],
    },
  },
};

export default preview;

Play Functions: Interaction Testing

// LoginForm.stories.tsx
import { within, userEvent, expect } from '@storybook/test';

export const FilledAndSubmitted: Story = {
  args: { onSubmit: fn() },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);

    // Simulate user interactions
    await userEvent.type(canvas.getByLabelText('Email'), '[email protected]');
    await userEvent.type(canvas.getByLabelText('Password'), 'secret123');
    await userEvent.click(canvas.getByRole('button', { name: 'Sign in' }));

    // Assert the outcome
    await expect(args.onSubmit).toHaveBeenCalledWith({
      email: '[email protected]',
      password: 'secret123',
    });
  },
};

export const ValidationErrors: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole('button', { name: 'Sign in' }));
    await expect(canvas.getByText('Email is required')).toBeVisible();
  },
};

Key Features

• Isolated development — build components without running the full application
• Controls addon — edit any prop interactively in the UI without code changes
• Docs addon — auto-generate API documentation from TypeScript types and JSDoc
• Accessibility addon — axe-core audit runs on every story automatically
• Play functions — interaction tests that run in CI via test-storybook
• Chromatic integration — pixel-perfect visual regression on every commit
• Framework support — React, Vue, Angular, Svelte, Web Components, Solid

Comparison: Storybook vs Alternatives

Pros & Cons