All articles

Front-end10 min read

Storybook: how to start and how far it's worth going

Storybook 10 from scratch: install it, write stories, test interaction and accessibility in Vitest and decide, level by level, how far it's worth going in your project.

Also in Português, Español, Français

Storybook is one of those tools everyone has heard of and few people use well. Either the project never installs it, or it installs it, writes three stories for the button and abandons it, or it tries to cover everything and ends up spending more time maintaining stories than building screens.

This post takes the middle road: it shows how to start in a few minutes and organizes what comes next into levels, so you can decide how far it makes sense to go in your project.

An honest note: everything here was done in a real project with Storybook 10.6, React 19 and Vite. The stories in the post run as tests and pass, and the accessibility check was confirmed by deliberately breaking a story with an unnamed button.

TL;DR#

  • Storybook is a showcase for your components, outside the app, in every state: empty, loading, with an error, with huge text.
  • Starting is one command: npm create storybook@latest. It detects the framework and already sets up testing and accessibility.
  • A story is just a component with data. The current format (CSF) is an object with args.
  • Stories become tests. With the Vitest addon, every story renders in a real browser, and play simulates the click and checks the result.
  • How far to go: for almost every project, stories for visual components, interaction tests and accessibility are enough. Visual testing and polished docs make sense in a design system and shared components.
  • Don't write stories for pages that depend on an API. A good story is for a component that gets everything through props.

What it's for#

Without Storybook, to see a component in a specific state you have to navigate the app to the right screen, with the right data. Seeing the order card with a huge customer name means creating a customer with a huge name. Seeing the empty list means deleting the orders.

With Storybook, each state becomes a story: a fixed entry that opens in one click. That helps with four things:

  • Developing the component in isolation, without depending on a backend, login or navigation.
  • Catching edge cases that almost never show up in the app: long text, an empty list, a zero value.
  • Talking to design and product, showing every state in one place.
  • Testing, because every story can become an automated test.

Level 0: install#

In an existing project, at the root:

npm create storybook@latest

The installer looks at the project's dependencies and picks the setup. In a React and Vite project, version 10.6 installed:

  • Storybook with the @storybook/react-vite framework;
  • @storybook/addon-vitest, which turns stories into tests;
  • @storybook/addon-a11y, which runs the accessibility check;
  • @storybook/addon-docs, which generates each component's documentation page;
  • @storybook/addon-mcp, the integration with AI assistants (more at the end);
  • Playwright with Chromium, which the tests use to render the stories.

And it created two scripts:

npm run storybook        # opens Storybook at localhost:6006
npm run build-storybook  # generates a static site in storybook-static/

The configuration lives in .storybook/:

.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
 
const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-mcp',
  ],
  framework: '@storybook/react-vite',
};
 
export default config;

The installer also creates a src/stories folder with examples (button, header, page). It's worth looking at once and deleting.

It works with Angular too: the documentation lists Angular 18 or newer, and the concepts below are the same. The examples in this post are in React.

Level 1: stories for visual components#

The examples use the components of an order list, the same ones from the post on smart and dumb components: OrderCard, OrderList and StatusFilter. They get everything through props, and that's exactly why they're easy to put in Storybook.

A story lives next to the component, in a .stories.tsx file:

OrderCard.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderCard } from './OrderCard';
 
const meta = {
  title: 'Orders/OrderCard',
  component: OrderCard,
  tags: ['autodocs'],
  args: {
    order: { id: '42', customer: 'Ana Souza', total: 189.9, status: 'paid' },
    onSelect: fn(),
  },
} satisfies Meta<typeof OrderCard>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Default: Story = {};
 
export const Selected: Story = {
  args: { selected: true },
};
 
export const LongCustomerName: Story = {
  args: {
    order: { id: '43', customer: 'Maria Aparecida dos Santos Albuquerque Ferreira', total: 12999.5, status: 'pending' },
  },
};
 
export const ClickingDetailsSendsTheId: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Details' }));
    await expect(args.onSelect).toHaveBeenCalledWith('42');
  },
};

Reading from top to bottom:

  • meta describes the component: its name in the sidebar (title), which component it is and the default args, which are the props.
  • fn() creates a spy function for onSelect. In Storybook, every call shows up in the actions panel.
  • Each export is a story. Default uses the default args, Selected changes only what it needs, LongCustomerName tests the edge case of the huge name.
  • tags: ['autodocs'] generates a documentation page with all the stories and a props table, taken from the TypeScript types.

What deserves a story is state, not random variation. For an order card: the default, the selected one, the long name, the high value. For a list: empty and with items.

OrderList.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderList } from './OrderList';
 
const meta = {
  title: 'Orders/OrderList',
  component: OrderList,
  args: { selectedId: null, onSelect: fn(), orders: [] },
} satisfies Meta<typeof OrderList>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Empty: Story = {
  play: async ({ canvas }) => {
    await expect(canvas.getByText('No orders here yet.')).toBeVisible();
  },
};
 
export const WithOrders: Story = {
  args: {
    selectedId: '2',
    orders: [
      { id: '1', customer: 'Ana', total: 89, status: 'paid' },
      { id: '2', customer: 'Bruno', total: 240, status: 'pending' },
      { id: '3', customer: 'Carla', total: 1320, status: 'shipped' },
    ],
  },
};

Level 2: controls and documentation#

This level comes almost for free. Since the props are in args, Storybook builds the Controls panel on its own: you can change the customer name, the status or the value right on screen and watch the component react. It's great for showing the component to people who don't code.

And autodocs puts it all together in one page per component. For a shared component, that page often replaces a README nobody updates.

Level 3: interaction tests#

This is where Storybook stops being a showcase and becomes a testing tool. The play function runs after the story appears on screen: it clicks, types and checks.

Go back to the last OrderCard story: ClickingDetailsSendsTheId clicks the "Details" button and checks that onSelect was called with the id '42'. Components with their own state work too:

StatusFilter.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { useState } from 'react';
import { expect } from 'storybook/test';
import { StatusFilter, type StatusFilterValue } from './StatusFilter';
 
const meta = {
  title: 'Orders/StatusFilter',
  component: StatusFilter,
  args: { value: 'all', onChange: () => {} },
  // Keeps the value in local state so the story behaves like the real screen.
  render: function Render(args) {
    const [value, setValue] = useState<StatusFilterValue>(args.value);
    return <StatusFilter value={value} onChange={setValue} />;
  },
} satisfies Meta<typeof StatusFilter>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Interactive: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'paid' }));
    await expect(canvas.getByRole('button', { name: 'paid' })).toHaveClass('active');
  },
};

The render keeps the value in a useState, so the story behaves like the real screen, and play clicks "paid" and checks that the button became active.

The most important part: with the Vitest addon, every story is a test, even the ones without play. A story that only renders already tests that the component doesn't break with that data. To run them all:

npx vitest run --project=storybook

In the post's project: 6 files, 15 tests, all passing, in a real Chromium, without opening a window. And you can run the same command in CI:

.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
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx vitest run --project=storybook

Level 4: accessibility#

The accessibility addon runs axe, the same library behind several browser extensions, on every story. The installer sets it up like this:

.storybook/preview.tsx
import type { Preview } from '@storybook/react-vite';
 
const preview: Preview = {
  parameters: {
    a11y: {
      // 'todo': shows violations in the UI only. 'error': fails the test.
      test: 'todo',
    },
  },
};
 
export default preview;

With 'todo', problems show up in the panel but break nothing. With 'error', they become test failures. To check, I created a story with a button that only has an icon and no text. With 'error', the test failed with axe's button-name rule: buttons need text that a screen reader can read.

A path that works well: start with 'todo', fix what shows up and switch to 'error' once it's clean. From then on, a new component with an accessibility problem doesn't get in.

An important limit: automated checks catch part of the problems, like missing names, contrast and wrong attributes. Reading order, focus and whether the experience makes sense with a screen reader still need manual testing.

Level 5: visual testing#

Interaction tests check behavior. Visual tests check appearance: they take a screenshot of each story and compare it with the previous one, warning you when a pixel changed. That's what catches the CSS change that broke a component on another screen.

The addon the installer added (@chromatic-com/storybook) connects Storybook to Chromatic, a paid service from the same team behind Storybook. In November 2026, the free plan gave 5,000 snapshots per month, on Chrome only.

It's worth it when many people touch the same components, as in a design system. In a small app, it usually costs more attention (reviewing differences that were expected) than it saves.

Level 6: AI#

addon-mcp connects Storybook to AI assistants. According to the documentation, the agent gets to know your components and their docs, generates stories and runs the interaction and accessibility tests to check its own work. The documentation itself warns that these features are in preview and may change.

The real value shows up when your Storybook is already well kept: the agent reuses the components that exist instead of inventing new ones. In a Storybook with three abandoned stories, it doesn't have much to learn from.

How far to go#

My recommendation, by type of project:

Up to level 4 is worth it for almost every project. Beyond that, it depends on how many people use the same components
  • Small app, one or two people: levels 0 to 3, only on the visual components you reuse. The gain is developing in isolation and getting interaction tests for free.
  • Team app: levels 0 to 4, with tests running in CI and accessibility set to 'error'.
  • Design system or shared library: every level. Here Storybook is the product: documentation, catalog and the guarantee that nothing changed by accident.

And what I wouldn't do in any case:

  • Stories for whole pages that fetch data. They require faking the API, auth and routing, and break with every backend change. If the screen has an important visual part, split that part into a component that receives props and write its story.
  • A story for every combination of props. Six sizes times four colors times two states helps nobody. Pick the states that matter and leave the rest to the controls panel.
  • Chasing 100% coverage. A story for a component nobody reuses and nobody touches is maintenance with no return.
  • Stories nobody runs. If the stories aren't in CI, they break silently and Storybook becomes a museum.

Common mistakes#

  • A component that fetches data inside itself. It doesn't get into Storybook without faking the API. The fix is almost always to split out the visual part, receiving everything through props.
  • Big args copied into every story. Put the default data in meta.args and change only what's needed in each story.
  • Actions without fn(). Without the spy function, play can't check what was called, and the actions panel stays empty.
  • Keeping the installer's examples. The sample button and page clutter the sidebar and the tests.
  • Accessibility stuck on 'todo'. A warning that never becomes an error ends up ignored.

Checklist#

  • Storybook installed with npm create storybook@latest, examples deleted.
  • Stories next to the visual components, with the states that matter (default, empty, long, error).
  • Default data in meta.args, event functions with fn().
  • autodocs on shared components.
  • play on the important behaviors (click, typing, selection).
  • npx vitest run --project=storybook running in CI.
  • Accessibility on 'error' once the project is clean.
  • Visual testing only if many people touch the same components.
  • No stories for pages that depend on an API.

References#

  • Front-end
  • storybook
  • react
  • testing
  • design-system
  • accessibility

Written by

Software engineer and designer. I write about what I run into while building apps, APIs and products.

Comments

Sign in with your GitHub account to comment.