storybook

Storybook: Develop, document, and test UI components in isolation

weekly downloads11.0M

versionv10.2.10

licenseMIT

categorytesting

storybookcomponentcomponentsdesign-systemscomponent-testingreactnextnext.jsreact-nativereact-native-webvueangularsveltesveltekitweb-components

Overview

Storybook is a frontend workshop that lets developers build, test, and document UI components in complete isolation from application logic. With over 10 million weekly downloads, it's the industry standard for component-driven development across React, Vue, Angular, Svelte, and Web Components. The package includes a CLI, dev server, manager UI, and core utilities for rendering component variations through props, mock data, and user interactions.

At its core, Storybook uses Component Story Format (CSF), an ES6 module-based standard where each story represents a specific component state. Stories are portable, framework-agnostic functions that can be reused across testing tools, visual regression systems, and documentation generators without vendor lock-in. This approach allows teams to develop components independently, verify edge cases systematically, and maintain a single source of truth for UI libraries.

The architecture centers on an extensible addon system with over 500 community plugins. Built-in features include interactive controls for live prop manipulation, action logging for event debugging, viewport simulators for responsive testing, and accessibility audits. Advanced addons enable visual regression testing, API mocking, Playwright integration for E2E tests, and automatic documentation generation. Teams deploy static Storybook builds to GitHub Pages or CDNs for shared component catalogs.

Storybook solves critical problems in modern frontend workflows: preventing component regressions through isolated testing, reducing context-switching by avoiding full app rebuilds, and enabling collaboration between designers and developers through interactive documentation. It's particularly valuable for design systems, component libraries, and enterprise applications where UI consistency and durability are non-negotiable.

Quick Start

typescript

// Button.stories.js - Component Story Format (CSF) example
import Button from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'danger'] },
    size: { control: 'radio', options: ['sm', 'md', 'lg'] }
  }
};

// Basic story with default args
export const Primary = {
  args: {
    variant: 'primary',
    children: 'Click me',
    onClick: () => console.log('clicked')
  }
};

// Story with interaction test using play function
export const WithInteraction = {
  args: { ...Primary.args },
  play: async ({ canvasElement }) => {
    const { userEvent, within } = await import('@storybook/test');
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
    await userEvent.click(button);
    // Verify state change or side effect
  }
};

// Disabled state for visual regression
export const Disabled = {
  args: {
    variant: 'secondary',
    children: 'Disabled',
    disabled: true
  }
};

// .storybook/main.js configuration
export default {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions'
  ],
  framework: '@storybook/react-vite',
  core: { builder: '@storybook/builder-vite' }
};

Use Cases

Component Library Development: Teams building shared component libraries use Storybook to showcase every variant and state (buttons, forms, modals) with live controls, allowing consumers to preview implementations before integrating into applications. The static build serves as both documentation and a sandbox for designers.

Visual Regression Testing: Engineers write stories for critical UI states, then integrate tools like Chromatic or Percy to automatically detect visual changes in CI pipelines. Each pull request gets screenshot comparisons of all component variations, catching unintended style regressions before merge.

Accessibility Audits: Using @storybook/addon-a11y, developers run automated WCAG compliance checks on every story. The addon highlights contrast issues, missing ARIA labels, and keyboard navigation problems directly in the Storybook UI during development, shifting accessibility left in the workflow.

Interaction Testing: With @storybook/test and the play function, teams write user interaction tests (clicks, form fills, API mocks) that run in the browser. These tests execute during development and in CI, validating component behavior without Selenium overhead.

Design System Documentation: Organizations maintain living style guides where designers reference token values, component APIs, and usage guidelines. Storybook auto-generates prop tables from TypeScript definitions, ensuring docs stay synchronized with code as the system evolves.

Pros & Cons

Pros

+Framework-agnostic with first-class React, Vue, Angular, Svelte support and 500+ addons for testing, accessibility, and visual regression
+Component Story Format is portable across tools with no vendor lock-in, enabling reuse in Jest, Playwright, and Chromatic workflows
+Static build deployment creates shareable component catalogs for cross-team collaboration without running backend services
+Built-in interaction testing and accessibility audits reduce external tooling dependencies for common QA workflows
+Massive ecosystem and mature documentation with 10M+ weekly downloads ensures long-term maintenance and community support

Cons

−Heavy initial setup with webpack/Vite config overhead compared to lightweight alternatives like Ladle for simple projects
−Build times can be slow for large component libraries with hundreds of stories, especially without caching optimizations
−Addon dependency can create version conflicts and maintenance burden as the ecosystem evolves independently from core
−Learning curve for advanced features like play functions, decorators, and custom webpack configurations requires time investment
−Default iframe isolation sometimes complicates global state management and CSS-in-JS theme providers, requiring workaround decorators

Comparisons

storybook vs chromatic

testing

Install

bash

npm install storybook

bash

pnpm add storybook

bash

bun add storybook

Overview

Quick Start

typescript

// Button.stories.js - Component Story Format (CSF) example
import Button from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'danger'] },
    size: { control: 'radio', options: ['sm', 'md', 'lg'] }
  }
};

// Basic story with default args
export const Primary = {
  args: {
    variant: 'primary',
    children: 'Click me',
    onClick: () => console.log('clicked')
  }
};

// Story with interaction test using play function
export const WithInteraction = {
  args: { ...Primary.args },
  play: async ({ canvasElement }) => {
    const { userEvent, within } = await import('@storybook/test');
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
    await userEvent.click(button);
    // Verify state change or side effect
  }
};

// Disabled state for visual regression
export const Disabled = {
  args: {
    variant: 'secondary',
    children: 'Disabled',
    disabled: true
  }
};

// .storybook/main.js configuration
export default {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions'
  ],
  framework: '@storybook/react-vite',
  core: { builder: '@storybook/builder-vite' }
};

Use Cases

Pros & Cons

Pros

+Framework-agnostic with first-class React, Vue, Angular, Svelte support and 500+ addons for testing, accessibility, and visual regression
+Component Story Format is portable across tools with no vendor lock-in, enabling reuse in Jest, Playwright, and Chromatic workflows
+Static build deployment creates shareable component catalogs for cross-team collaboration without running backend services
+Built-in interaction testing and accessibility audits reduce external tooling dependencies for common QA workflows
+Massive ecosystem and mature documentation with 10M+ weekly downloads ensures long-term maintenance and community support

Cons

−Heavy initial setup with webpack/Vite config overhead compared to lightweight alternatives like Ladle for simple projects
−Build times can be slow for large component libraries with hundreds of stories, especially without caching optimizations
−Addon dependency can create version conflicts and maintenance burden as the ecosystem evolves independently from core
−Learning curve for advanced features like play functions, decorators, and custom webpack configurations requires time investment
−Default iframe isolation sometimes complicates global state management and CSS-in-JS theme providers, requiring workaround decorators