Storybook 8 Complete Guide: Component-Driven UI Development (2026)

Storybook is the industry-standard UI component workshop for building, testing, and documenting components in isolation. With Storybook 8, teams can develop UI components independently from business logic and backend dependencies, run interaction tests with play functions, catch visual regressions with Chromatic, and generate living documentation automatically. Whether you work with React, Vue, Angular, or Svelte, Storybook provides a unified environment for component-driven development that scales from solo projects to enterprise design systems.

What Is Storybook and Component-Driven Development?

Storybook is an open-source tool that provides a sandboxed environment for developing UI components in isolation. Instead of navigating through your entire application to see a specific component state, you define stories that render your component with different props, states, and contexts. Each story is a named export that captures a specific variation of your component.

Component-driven development (CDD) is a methodology where you build UIs from the bottom up, starting with atomic components (buttons, inputs, badges), composing them into molecules (search bars, cards), and assembling molecules into organisms and pages. Storybook is the primary tool that enables this workflow by providing an isolated development environment with hot module replacement, responsive viewport controls, and a rich addon ecosystem.

Storybook vs Alternatives

While Storybook dominates the component workshop space, alternatives exist. Ladle is a lightweight alternative built on Vite that focuses on React components with faster startup. Histoire supports Vue and Svelte with a similar story-based approach. Styleguidist generates style guides from JSDoc comments. React Cosmos provides fixtures-based component exploration. However, Storybook has the largest ecosystem with 400+ addons, the most framework support, and the strongest CI/CD integration story through Chromatic.

Feature Comparison: Storybook vs Alternatives
┌──────────────────┬────────────┬────────┬──────────┬──────────────┐
│ Feature          │ Storybook  │ Ladle  │ Histoire │ React Cosmos │
├──────────────────┼────────────┼────────┼──────────┼──────────────┤
│ React            │ Yes        │ Yes    │ No       │ Yes          │
│ Vue              │ Yes        │ No     │ Yes      │ No           │
│ Angular          │ Yes        │ No     │ No       │ No           │
│ Svelte           │ Yes        │ No     │ Yes      │ No           │
│ Addons           │ 400+       │ ~10    │ ~20      │ ~15          │
│ Visual Testing   │ Chromatic  │ Manual │ Manual   │ Manual       │
│ Play Functions   │ Yes        │ No     │ No       │ No           │
│ MDX Docs         │ Yes        │ No     │ Yes      │ No           │
│ CI Test Runner   │ Yes        │ No     │ No       │ No           │
│ Build Tool       │ Vite       │ Vite   │ Vite     │ Webpack      │
└──────────────────┴────────────┴────────┴──────────┴──────────────┘

Setting Up Storybook for React, Vue, Angular, and Svelte

Storybook 8 provides a zero-config setup experience. The init command detects your framework, installs dependencies, and generates configuration files automatically. Storybook 8 is built on Vite by default for all frameworks, delivering significantly faster startup and hot module replacement.

React Setup

# Initialize Storybook in a React project
npx storybook@latest init

# Or create a new React project with Storybook
npx create-react-app my-app --template typescript
cd my-app
npx storybook@latest init

Vue Setup

# Initialize Storybook in a Vue 3 project
npm create vue@latest my-vue-app
cd my-vue-app
npx storybook@latest init

Angular Setup

# Initialize Storybook in an Angular project
ng new my-angular-app
cd my-angular-app
npx storybook@latest init

Svelte Setup

# Initialize Storybook in a SvelteKit project
npx sv create my-svelte-app
cd my-svelte-app
npx storybook@latest init

After initialization, Storybook creates a .storybook directory with two key configuration files: main.ts for build configuration and preview.ts for runtime configuration that applies to all stories.

// .storybook/main.ts
import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  stories: [
    "../src/**/*.mdx",
    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)",
  ],
  addons: [
    "@storybook/addon-onboarding",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
    "@storybook/addon-a11y",
  ],
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
};
export default config;

// .storybook/preview.ts
import type { Preview } from "@storybook/react";

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)/i,
        date: /Date$/i,
      },
    },
  },
};
export default preview;

Writing Stories with CSF3 Format

Component Story Format 3 (CSF3) is the latest story format in Storybook 8. Stories are defined as plain objects instead of functions, making them more concise and composable. Each file has a default export (meta) that describes the component and named exports that define individual stories.

CSF3 introduces the concept of story-level args that automatically generate Controls UI, allowing non-developers to explore component variations interactively. Stories can also extend other stories, reducing duplication when testing variations of the same base state.

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

// Meta describes the component
const meta = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "danger"],
    },
    size: {
      control: "radio",
      options: ["sm", "md", "lg"],
    },
  },
} satisfies Meta<typeof Button>;

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

// Each named export is a story
export const Primary: Story = {
  args: {
    variant: "primary",
    size: "md",
    children: "Click me",
  },
};

export const Secondary: Story = {
  args: {
    ...Primary.args,
    variant: "secondary",
  },
};

export const Danger: Story = {
  args: {
    ...Primary.args,
    variant: "danger",
    children: "Delete",
  },
};

export const Large: Story = {
  args: {
    ...Primary.args,
    size: "lg",
    children: "Large Button",
  },
};

Args, Controls, and ArgTypes

Args are the mechanism for defining and manipulating component props in Storybook. When you define args on a story, Storybook automatically generates a Controls panel that lets users modify those props interactively. ArgTypes provide metadata about args, allowing you to customize the control type, set valid options, add descriptions, and define default values.

Controls support a wide range of input types: text inputs, number inputs, booleans, radio buttons, select dropdowns, color pickers, date pickers, range sliders, and object/array editors. Storybook infers the correct control type from your TypeScript prop types or PropTypes, but you can override them via argTypes.

// src/components/Card.stories.ts
import type { Meta, StoryObj } from "@storybook/react";
import { Card } from "./Card";

const meta = {
  title: "Components/Card",
  component: Card,
  argTypes: {
    title: { control: "text", description: "Card heading" },
    description: { control: "text" },
    imageUrl: { control: "text" },
    variant: {
      control: "select",
      options: ["default", "elevated", "outlined"],
      table: {
        defaultValue: { summary: "default" },
      },
    },
    isLoading: { control: "boolean" },
    rating: {
      control: { type: "range", min: 0, max: 5, step: 0.5 },
    },
    backgroundColor: { control: "color" },
    publishedAt: { control: "date" },
    tags: { control: "object" },
    onClick: { action: "clicked" },
  },
} satisfies Meta<typeof Card>;

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

export const Default: Story = {
  args: {
    title: "Getting Started with Storybook",
    description: "Learn how to build components in isolation.",
    variant: "default",
    isLoading: false,
    rating: 4.5,
    tags: ["tutorial", "react"],
  },
};

Decorators and Parameters

Decorators wrap stories with additional rendering logic. They are essential for providing context that components need, such as theme providers, router contexts, internationalization providers, or Redux stores. Decorators can be applied at the story level, component level, or globally in preview.ts.

Parameters are static metadata attached to stories that configure addon behavior. For example, you can set the viewport size, background color, disable specific addons, or configure the layout mode. Like decorators, parameters cascade from global to component to story level.

// .storybook/preview.tsx - Global decorators
import type { Preview } from "@storybook/react";
import { ThemeProvider } from "../src/theme";
import { MemoryRouter } from "react-router-dom";
import "../src/globals.css";

const preview: Preview = {
  decorators: [
    // Wrap all stories with ThemeProvider
    (Story) => (
      <ThemeProvider>
        <Story />
      </ThemeProvider>
    ),
    // Wrap all stories with Router
    (Story) => (
      <MemoryRouter initialEntries={["/"]}>
        <Story />
      </MemoryRouter>
    ),
  ],
  parameters: {
    layout: "centered",
    backgrounds: {
      default: "light",
      values: [
        { name: "light", value: "#ffffff" },
        { name: "dark", value: "#1a1a2e" },
        { name: "gray", value: "#f5f5f5" },
      ],
    },
    viewport: {
      viewports: {
        mobile: { name: "Mobile", styles: { width: "375px", height: "667px" } },
        tablet: { name: "Tablet", styles: { width: "768px", height: "1024px" } },
        desktop: { name: "Desktop", styles: { width: "1440px", height: "900px" } },
      },
    },
  },
};
export default preview;

Play Functions for Interaction Testing

Play functions are one of the most powerful features in Storybook 8. They let you write interaction tests directly inside stories using Testing Library and expect assertions. When a story with a play function loads, Storybook automatically executes the interactions and reports pass/fail results in the Interactions panel.

Play functions run in the browser, so they test actual DOM behavior. You can simulate user clicks, keyboard input, form submission, drag and drop, and more. Combined with the test-runner package, play functions can be executed in CI to catch regressions automatically.

// src/components/LoginForm.stories.ts
import type { Meta, StoryObj } from "@storybook/react";
import { within, userEvent, expect } from "@storybook/test";
import { LoginForm } from "./LoginForm";

const meta = {
  title: "Forms/LoginForm",
  component: LoginForm,
} satisfies Meta<typeof LoginForm>;

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

export const FilledForm: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    // Type into the email field
    await userEvent.type(
      canvas.getByLabelText("Email"),
      "user@example.com"
    );

    // Type into the password field
    await userEvent.type(
      canvas.getByLabelText("Password"),
      "securePassword123"
    );

    // Click the submit button
    await userEvent.click(
      canvas.getByRole("button", { name: /sign in/i })
    );

    // Assert the success message appears
    await expect(
      canvas.getByText("Welcome back!")
    ).toBeInTheDocument();
  },
};

export const ValidationError: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    // Submit without filling fields
    await userEvent.click(
      canvas.getByRole("button", { name: /sign in/i })
    );

    // Assert validation errors
    await expect(
      canvas.getByText("Email is required")
    ).toBeInTheDocument();
  },
};

Visual Regression Testing with Chromatic

Visual regression testing compares screenshots of your components across commits to catch unintended visual changes. Chromatic is the official cloud service built by the Storybook team that captures a screenshot of every story in every browser and viewport, then diffs them against the baseline.

When Chromatic detects a visual change, it creates a review for your team. Reviewers can approve intentional changes (updating the baseline) or reject regressions. This workflow integrates with GitHub pull requests, so visual reviews happen alongside code reviews.

# Install Chromatic
npm install --save-dev chromatic

# Run visual tests (first time creates baselines)
npx chromatic --project-token=YOUR_TOKEN

# In CI (GitHub Actions example)
# .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: \${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          # Enable TurboSnap for faster builds
          onlyChanged: true

Accessibility Testing with the a11y Addon

The a11y addon integrates axe-core accessibility testing into Storybook. It runs automated audits against every story and reports violations, passes, and incomplete checks in a dedicated panel. This catches common WCAG violations like missing alt text, insufficient color contrast, missing form labels, and incorrect ARIA attributes.

You can configure severity levels and rule overrides per story or globally. Combined with play functions, you can test accessibility in interactive states like open dropdowns, focused inputs, and error messages that only appear after user interaction.

# Install the a11y addon
npm install --save-dev @storybook/addon-a11y

// .storybook/main.ts - Add to addons
addons: [
  "@storybook/addon-essentials",
  "@storybook/addon-a11y",
],

// Configure a11y rules per story
export const DarkMode: Story = {
  args: { theme: "dark" },
  parameters: {
    a11y: {
      config: {
        rules: [
          // Disable a specific rule for this story
          { id: "color-contrast", enabled: false },
        ],
      },
    },
  },
};

// Combine a11y with play function
export const DropdownOpen: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    // Open dropdown so a11y addon audits the open state
    await userEvent.click(canvas.getByRole("button"));
    await expect(canvas.getByRole("listbox")).toBeVisible();
  },
};

Documentation with MDX

Storybook supports MDX (Markdown + JSX) for writing rich documentation pages alongside your stories. MDX docs can embed live story previews, component prop tables (generated from TypeScript types), code snippets, and custom React components. This creates living documentation that stays in sync with your actual components.

Storybook 8 uses autodocs by default, automatically generating a documentation page for each component from its stories and JSDoc comments. You can override this with a custom MDX file when you need more detailed documentation with usage guidelines, design rationale, or complex examples.

// src/components/Button.mdx
import { Meta, Story, Canvas, Controls } from "@storybook/blocks";
import * as ButtonStories from "./Button.stories";

<Meta of={ButtonStories} />

# Button

The Button component is the primary interactive element
in our design system. Use it for actions and navigation.

## Usage Guidelines

- Use **Primary** for the main call to action
- Use **Secondary** for supporting actions
- Use **Danger** only for destructive actions

## Interactive Demo

<Canvas of={ButtonStories.Primary} />
<Controls of={ButtonStories.Primary} />

## All Variants

<Canvas>
  <Story of={ButtonStories.Primary} />
  <Story of={ButtonStories.Secondary} />
  <Story of={ButtonStories.Danger} />
</Canvas>

Addons Ecosystem

Storybook has the largest addon ecosystem of any component workshop, with over 400 community addons. Official addons include Controls, Actions (event logging), Viewport (responsive preview), Backgrounds, Measure, Outline, and the Accessibility addon. Community addons extend functionality with tools like storybook-dark-mode, storybook-addon-designs (Figma embeds), storybook-addon-performance, and msw-storybook-addon for API mocking.

Addons hook into the Storybook lifecycle through a well-defined API. They can add panels, toolbar buttons, decorators, and custom tabs. Building a custom addon involves creating a manager (toolbar/panel UI) and a decorator (story wrapper) that communicate through a channel API.

# Essential addons (included by default)
npm install @storybook/addon-essentials
# Includes: Controls, Actions, Viewport, Backgrounds,
#   Toolbars, Measure, Outline, Docs

# Popular community addons
npm install storybook-dark-mode           # Dark mode toggle
npm install @storybook/addon-designs      # Figma embeds
npm install msw-storybook-addon           # API mocking with MSW
npm install storybook-addon-performance   # Performance profiling
npm install @storybook/addon-coverage      # Code coverage

// .storybook/main.ts
const config: StorybookConfig = {
  addons: [
    "@storybook/addon-essentials",
    "@storybook/addon-a11y",
    "@storybook/addon-interactions",
    "storybook-dark-mode",
    "@storybook/addon-designs",
  ],
};

// Using MSW addon to mock API calls in stories
import { http, HttpResponse } from "msw";

export const WithData: Story = {
  parameters: {
    msw: {
      handlers: [
        http.get("/api/users", () => {
          return HttpResponse.json([
            { id: 1, name: "Alice", role: "admin" },
            { id: 2, name: "Bob", role: "user" },
          ]);
        }),
      ],
    },
  },
};

export const WithError: Story = {
  parameters: {
    msw: {
      handlers: [
        http.get("/api/users", () => {
          return HttpResponse.json(
            { error: "Internal Server Error" },
            { status: 500 }
          );
        }),
      ],
    },
  },
};

TypeScript Integration

Storybook 8 has first-class TypeScript support. The Meta and StoryObj types provide full type checking for your stories, ensuring args match your component props, play functions have the correct context, and decorators return valid JSX. TypeScript prop types are automatically extracted to generate ArgTypes and Controls.

The satisfies operator in TypeScript works especially well with CSF3, providing type checking without widening the type. This ensures your stories are type-safe while still allowing Storybook to infer the specific args for each story.

// Full TypeScript example with strict typing
import type { Meta, StoryObj } from "@storybook/react";
import { DataTable, type DataTableProps } from "./DataTable";

type User = {
  id: number;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};

// satisfies provides type checking without widening
const meta = {
  title: "Data/DataTable",
  component: DataTable<User>,
  tags: ["autodocs"],
  argTypes: {
    sortDirection: {
      control: "radio",
      options: ["asc", "desc"] as const,
    },
    onRowClick: { action: "row-clicked" },
  },
} satisfies Meta<DataTableProps<User>>;

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

const sampleUsers: User[] = [
  { id: 1, name: "Alice", email: "alice@co.com", role: "admin" },
  { id: 2, name: "Bob", email: "bob@co.com", role: "editor" },
];

export const Default: Story = {
  args: {
    data: sampleUsers,
    columns: ["name", "email", "role"],
    sortable: true,
    sortDirection: "asc",
  },
};

CI/CD Integration

Storybook integrates into continuous integration pipelines through the test-runner package and Chromatic. The test-runner executes all play functions in a headless browser (Playwright), reporting results in standard test formats. Chromatic runs visual and interaction tests in the cloud, providing parallelized execution across browsers.

A typical CI pipeline runs the Storybook test-runner for interaction tests, publishes to Chromatic for visual regression tests, and deploys the built Storybook as a static site for stakeholder review. GitHub Actions, GitLab CI, and CircleCI all have official guides.

# Install the test runner
npm install --save-dev @storybook/test-runner

# Run interaction tests locally
npx test-storybook

# Run with coverage
npx test-storybook --coverage

# package.json scripts
"scripts": {
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build",
  "test-storybook": "test-storybook",
  "test-storybook:ci": "concurrently -k -s first \
    \"npx http-server storybook-static -p 6006\" \
    \"npx wait-on tcp:6006 && test-storybook\""
}

# GitHub Actions workflow
# .github/workflows/storybook.yml
name: Storybook Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build-storybook
      - run: npm run test-storybook:ci
      - uses: chromaui/action@latest
        with:
          projectToken: \${{ secrets.CHROMATIC_TOKEN }}

Performance Optimization and Best Practices

As your component library grows, Storybook build and startup times can increase. These best practices keep your workflow fast and your stories maintainable.

• Use the Vite builder (default in Storybook 8) for significantly faster startup and HMR compared to Webpack.
• Enable lazy compilation in development so only the stories you navigate to are compiled, reducing initial startup time.
• Write one story file per component and co-locate it next to the component file for discoverability.
• Use args instead of hardcoded props in stories to make every variation explorable through Controls.
• Apply decorators at the lowest possible level to avoid unnecessary re-renders when switching stories.
• Use play functions for interaction tests instead of separate testing files to keep tests close to stories.
• Configure autodocs for automatic documentation generation instead of manually maintaining MDX files.
• Mock external dependencies (API calls, routers, stores) using decorators and MSW instead of real backends.
• Use the composition feature to combine multiple Storybooks from different packages in a monorepo.
• Set up Chromatic TurboSnap to only capture snapshots of stories affected by code changes, reducing CI time and cost.

// Recommended project structure
src/
  components/
    Button/
      Button.tsx            # Component
      Button.stories.ts     # Stories (co-located)
      Button.test.ts        # Unit tests
      Button.mdx            # Custom docs (optional)
      Button.module.css     # Styles
      index.ts              # Barrel export
    Card/
      Card.tsx
      Card.stories.ts
      index.ts
  .storybook/
    main.ts                 # Build config
    preview.ts              # Runtime config
    manager.ts              # UI customization

Frequently Asked Questions