# Storybook

> Storybook is a frontend workshop for building UI components and pages in isolation. It helps with UI development, testing, and documentation.

Current version: Version 10.4 (10.4)

## Documentation

- [Storybook Docs](https://storybook.js.org/docs): Main documentation
- [Full Documentation (Markdown)](https://storybook.js.org/llms-full.txt): Complete documentation in plain text for LLM consumption

## Markdown Access

Append `.md` to any docs URL to get clean markdown with code examples:
- `https://storybook.js.org/docs/writing-stories/decorators.md`
- `https://storybook.js.org/docs/9/writing-stories/decorators.md` (Version 9)

### Query Parameters

All markdown endpoints (`.md` URLs and `llms-full.txt`) support these query parameters:
- `renderer` - Framework filter for code snippets (default: `react`). Options: `react`, `vue`, `angular`, `svelte`, `web-components`, `solid`, `preact`, `html`, `ember`, `qwik`
- `language` - Language filter for code snippets (default: `ts`). Options: `ts`, `js`
- `codeOnly` - When `true`, returns only the code snippets without prose

Examples:
- `GET /docs/writing-stories/decorators.md?renderer=vue&language=ts`
- `GET /docs/writing-stories/decorators.md?codeOnly=true`
- `GET /llms-full.txt?renderer=angular&language=js`

### Versioned Access

Prefix the path with a version slug for older versions:
---
# Why Storybook?

## The problem

The web’s universality is pushing more complexity into the frontend. It began with responsive web design, which turned every user interface from one to 10, 100, 1000 different user interfaces. Over time, additional requirements piled on like devices, browsers, accessibility, performance, and async states.

Component-driven tools like React, Vue 3, and Angular help break down complex UIs into simple components but they’re not silver bullets. As frontends grow, the number of components swells. Mature projects can contain hundreds of components that yield thousands of discrete variations.

To complicate matters further, those UIs are painful to debug because they’re entangled in business logic, interactive states, and app context.

The breadth of modern frontends overwhelm existing workflows. Developers must consider countless UI variations, yet aren’t equipped to develop or organize them all. You end up in a situation where UIs are tougher to build, less satisfying to work on, and brittle.

![UI multiverse](../_assets/get-started/multiverse.png)

## The solution

### Build UIs in isolation

Every piece of UI is now a [component](https://www.componentdriven.org/). The superpower of components is that you don't need to spin up the whole app just to see how they render. You can render a specific variation in isolation by passing in props, mocking data, or faking events.

Storybook is packaged as a small, development-only, [workshop](https://bradfrost.com/blog/post/a-frontend-workshop-environment/) that lives alongside your app. It provides an isolated iframe to render components without interference from app business logic and context. That helps you focus development on each variation of a component, even the hard-to-reach edge cases.

### Capture UI variations as “stories”

When developing a component variation in isolation, save it as a story. [Stories](https://storybook.js.org/docs/writing-stories.md) are a declarative syntax for supplying props and mock data to simulate component variations. Each component can have multiple stories. Each story allows you to demonstrate a specific variation of that component to verify appearance and behavior.

You write stories for granular UI component variation and then use those stories in development, testing, and documentation.

```ts
// Histogram.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const Basic: Story = {
  args: {
    dataType: 'latency',
    showHistogramLabels: true,
    histogramAccentColor: '#1EA7FD',
    label: 'Latency distribution',
  },
};
```

```ts
// Histogram.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Histogram,
});

export const Basic = meta.story({
  args: {
    dataType: 'latency',
    showHistogramLabels: true,
    histogramAccentColor: '#1EA7FD',
    label: 'Latency distribution',
  },
});
```

### Storybook keeps track of every story

Storybook is an interactive directory of your UI components and their stories. In the past, you'd have to spin up the app, navigate to a page, and contort the UI into the right state. This is a huge waste of time and bogs down frontend development. With Storybook, you can skip all those steps and jump straight to working on a UI component in a specific state.

<details>
<summary>Where does Storybook fit into my project?</summary>

Storybook is packaged as a small, development-only, [workshop](https://bradfrost.com/blog/post/a-frontend-workshop-environment/) that lives alongside your app. Install it by [running a command](https://storybook.js.org/docs/get-started/install.md).

During development, run it in a separate node process. If you’re working on UI in isolation, the only thing you’ll need to run is Storybook.

</details>

<details>
<summary>Does Storybook work with my favorite libraries?</summary>

Storybook aims to integrate with industry-standard tools and platforms to simplify setup. Thanks to our ambitious developer community, we’ve made significant progress. There are hundreds of [addons](https://storybook.js.org/addons/) and tutorials that walk through how to set up Storybook in all types of projects.

If you’re using a niche framework or a recently launched tool, we might not have an integration for it yet. Consider creating a [proof of concept](https://storybook.js.org/docs/addons/writing-addons.md) yourself first to lead the way for the rest of the community.

</details>

<details>
<summary>What’s the recommended Storybook workflow?</summary>

Every team is different and so is their workflow. Storybook is designed to be incrementally adoptable. Teams can gradually try features to see what works best for them.

Most community members choose a [Component-Driven](https://www.componentdriven.org/) workflow. UIs are developed in isolation from the “bottom up” starting with basic components then progressively combined to assemble pages.

1. Build each component in isolation and write stories for its variations.
2. Compose small components together to enable more complex functionality.
3. Assemble pages by combining composite components.
4. Integrate pages into your project by hooking up data and business logic.

</details>

## Benefits

When you write stories for components, you get a bunch of additional benefits for free.

**📝 Develop UIs that are more durable**

Isolate components and pages and track their use cases as [stories](https://storybook.js.org/docs/writing-stories.md). Verify hard-to-reach edge cases of UI. Use addons to mock everything a component needs—context, API requests, device features, etc.

**✅ Test UIs with less effort and no flakes**

Stories are a pragmatic, reproducible way of tracking UI states. Use them to spot-test the UI during development. Storybook offers built-in workflows for automated [Interaction](https://storybook.js.org/docs/writing-tests/interaction-testing.md), [Accessibility](https://storybook.js.org/docs/writing-tests/accessibility-testing.md), and [Visual](https://storybook.js.org/docs/writing-tests/visual-testing.md) testing. Or use stories as test cases by [importing them into other JavaScript testing tools](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md).

**📚 Document UI for your team to reuse**

Storybook is the single source of truth for your UI. Stories index all your components and their various states, making it easy for your team to find and reuse existing UI patterns. Storybook also auto-generates [documentation](https://storybook.js.org/docs/writing-docs.md) from those stories.

**📤 Share how the UI actually works**

Stories show how UIs actually work, not just a picture of how they're supposed to work. That keeps everyone aligned on what's currently in production. [Publish Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md) to get sign-off from teammates. Or [embed](https://storybook.js.org/docs/sharing/embed.md) them in wikis, Markdown, and Figma to streamline collaboration.

**🚦Automate UI workflows**

Storybook is compatible with your continuous integration workflow. Add it as a CI step to automate user interface testing, review implementation with teammates, and get signoff from stakeholders.

## Write stories once, reuse everywhere

Storybook is powered by [Component Story Format](https://storybook.js.org/docs/api/csf.md), an open standard based on JavaScript ES6 modules. This enables stories to interoperate between development, testing, and design tools. Each story is exported as a JavaScript function enabling you to reuse it with other tools. No vendor lock-in.

Reuse stories with [Jest](https://jestjs.io/) or [Vitest](https://vitest.dev/) and [Testing Library](https://testing-library.com/) to verify interactions. Put them in [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) for visual testing. Audit story accessibility with [Axe](https://github.com/dequelabs/axe-core). Or test user flows with [Playwright](https://playwright.dev/) and [Cypress](https://www.cypress.io/). Reuse unlocks more workflows at no extra cost.

---

Storybook is purpose-built to help you develop complex UIs faster with greater durability and lower maintenance. It’s used by 100s of [leading companies](https://storybook.js.org/showcase) and thousands of [developers](https://github.com/storybookjs/storybook/).
> Source: https://storybook.js.org/docs/get-started/why-storybook
---

# Install Storybook

Use the Storybook CLI to install it in a single command. Run this inside your project’s root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

Ask your AI agent to [set up Storybook for you](https://storybook.js.org/docs/ai/setup.md).

Storybook will look into your project's dependencies during its install process and provide you with the best configuration available.

## Project requirements

Storybook is designed to work with a variety of frameworks and environments. If your project is using one of the packages listed here, please ensure that you have the following versions installed:

<div style={{ columns: 2, marginBottom: "1.5rem" }}>

- Angular 18+
- Lit 3+
- Next.js 14+
- Node.js 20+
- npm 10+
- pnpm 9+
- Preact 8+
- React Native 0.72+
- React Native Web 0.19+
- Svelte 5+
- SvelteKit 1+
- TypeScript 4.9+
- Vite 5+
- Vitest 3+
- Vue 3+
- Webpack 5+
- Yarn 4+

</div>

Additionally, the Storybook app supports the following browsers:

- Chrome 131+
- Edge 134+
- Firefox 136+
- Safari 18.3+
- Opera 117+

<details>
<summary>How do I use Storybook with older browsers?</summary>

You can use Storybook with older browsers in two ways:

1. Use a version of Storybook prior to `9.0.0`, which will have less strict requirements.
2. Develop or build your Storybook in ["preview-only" mode](https://storybook.js.org/docs/sharing/publish-storybook.md#build-storybook-for-older-browsers), which can be used in older, unsupported browsers.

</details>

## Installation

Run this command inside your project's root directory to install the latest version of Storybook:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

<details id="custom-storybook-version">
<summary>Install a specific version</summary>

To install Storybook 8.3 or newer, you can use the `create` command with a specific version:

```shell
npm create storybook@8.3
```

```shell
pnpm create storybook@8.3
```

To install a Storybook version prior to 8.3, you must use the `init` command:

```shell
npx storybook@8.2 init
```

```shell
pnpm dlx storybook@8.2 init
```

```shell
yarn dlx storybook@8.2 init
```

For either command, you can specify either an npm tag such as `latest` or `next`, or a (partial) version number. For example:

- `storybook@latest init` will initialize the latest version
- `storybook@7.6.10 init` will initialize `7.6.10`
- `storybook@7 init` will initialize the newest `7.x.x` version

</details>

When installing, Storybook will present you with a series of interactive prompts to help customize your installation:

**New to Storybook?**

Storybook will ask if you're new to Storybook. If you select "Yes":

- You will be welcomed with an interactive tour
- Example stories will be created to help you learn

If you're experienced with Storybook, you can skip the onboarding to get a minimal setup.

**What configuration should we install?**

Storybook will ask what type of configuration you want to install:

- **Recommended**: Includes component development, [documentation](https://storybook.js.org/docs/writing-docs/autodocs.md), [testing](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), and [accessibility](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) features
- **Minimal**: Just the essentials for component development

You can also manually select these features using the `--features` flag. For example:

```bash
npm create storybook@latest --features docs test a11y
```

After completing the prompts, the command above will make the following changes to your local environment:

- 📦 Install the required dependencies.
- 🛠 Set up the necessary scripts to run and build Storybook.
- 🛠 Add the default Storybook configuration.
- 📝 Add some boilerplate stories to get you started.
- 📡 Set up telemetry to help us improve Storybook. Read more about it [here](https://storybook.js.org/docs/configure/telemetry.md).

## Run the Setup Wizard

If all goes well, you should see a setup wizard that will help you get started with Storybook introducing you to the main concepts and features, including how the UI is organized, how to write your first story, and how to test your components' response to various inputs utilizing [controls](https://storybook.js.org/docs/essentials/controls.md).

![Storybook onboarding](../_assets/get-started/example-onboarding-wizard.png)

If you skipped the wizard, you can always run it again by adding the `?path=/onboarding` query parameter to the URL of your Storybook instance, provided that the example stories are still available.

## Start Storybook

Storybook comes with a built-in development server featuring everything you need for project development. Depending on your system configuration, running the `storybook` command will start the local development server, output the address for you, and automatically open the address in a new browser tab where a welcome screen greets you.

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out) if you'd not like to share any information.

![Storybook welcome screen](../_assets/get-started/example-welcome.png)

There are some noteworthy items here:

- A collection of useful links for more in-depth configuration and customization options you have at your disposal.
- A second set of links for you to expand your Storybook knowledge and get involved with the ever-growing Storybook community.
- A few example stories to get you started.

<details>
<summary>
<h3 id="troubleshooting">Troubleshooting</h3>
</summary>
#### Run Storybook with other package managers

The Storybook CLI includes support for the industry's popular package managers (e.g., [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/)) automatically detecting the one you are using when you initialize Storybook. However, if you want to use a specific package manager as the default, add the `--package-manager` flag to the installation command. For example:

```shell
npm create storybook@latest --package-manager=npm
```

```shell
pnpm create storybook@latest --package-manager=npm
```

```shell
yarn create storybook --package-manager=npm
```

#### The CLI doesn't detect my framework

If auto‑detection fails or you’re using a custom setup, pass the project type explicitly with `--type` when running the initializer. The allowed values are:

| Type                   | Framework                        |
| ---------------------- | -------------------------------- |
| `angular`              | Angular                          |
| `ember`                | Ember                            |
| `html`                 | HTML                             |
| `nextjs`               | Next.js                          |
| `nuxt`                 | Nuxt                             |
| `preact`               | Preact                           |
| `qwik`                 | Qwik                             |
| `react`                | React                            |
| `react_native`         | React Native                     |
| `react_native_web`     | React Native Web                 |
| `react_native_and_rnw` | React Native (+ Web)             |
| `react_scripts`        | Create React App (react-scripts) |
| `react_project`        | React Project                    |
| `server`               | Server renderer                  |
| `solid`                | Solid                            |
| `svelte`               | Svelte                           |
| `sveltekit`            | SvelteKit                        |
| `vue3`                 | Vue 3                            |
| `web_components`       | Web Components                   |

```shell
npm create storybook@latest --type solid
```

```shell
pnpm create storybook@latest --type solid
```

```shell
yarn create storybook --type solid
```

#### Yarn Plug'n'Play (PnP) support with Storybook

If you've enabled Storybook in a project running on a new version of Yarn with [Plug'n'Play](https://yarnpkg.com/features/pnp) (PnP) enabled, you may notice that it will generate `node_modules` with some additional files and folders. This is a known constraint as Storybook relies on some directories (e.g., `.cache`) to store cache files and other data to improve performance and faster builds. You can safely ignore these files and folders, adjusting your `.gitignore` file to exclude them from the version control you're using.

#### Run Storybook with Webpack 4

If you previously installed Storybook in a project that uses Webpack 4, it will no longer work. This is because Storybook now uses Webpack 5 by default. To solve this issue, we recommend you upgrade your project to Webpack 5 and then run the following command to migrate your project to the latest version of Storybook:

```shell
npx storybook@latest automigrate
```

```shell
pnpm dlx storybook@latest automigrate
```

```shell
yarn dlx storybook@latest automigrate
```

#### Storybook doesn't work with an empty directory

By default, Storybook is configured to detect whether you're initializing it on an empty directory or an existing project. However, if you attempt to initialize Storybook, select a Vite-based framework (e.g., [React](https://storybook.js.org/docs/get-started/frameworks/react-vite.md)) in a directory that only contains a `package.json` file, you may run into issues with [Yarn Modern](https://yarnpkg.com/getting-started). This is due to how Yarn handles peer dependencies and how Storybook is set up to work with Vite-based frameworks, as it requires the [Vite](https://vitejs.dev/) package to be installed. To solve this issue, you must install Vite manually and initialize Storybook.

#### The installation process seems flaky and keeps failing

If you're still running into some issues during the installation process, we encourage you to check out the following resources:

- Storybook's React Vite [framework documentation](https://storybook.js.org/docs/get-started/frameworks/react-vite.md) for more information on how to set up Storybook in your React project with Vite.
- Storybook's React Webpack [framework documentation](https://storybook.js.org/docs/get-started/frameworks/react-webpack5.md) for more information on how to set up Storybook in your React project with Webpack 5.
- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help.

</details>

Now that you have successfully installed Storybook and understood how it works, let's continue where you left off in the [setup wizard](#run-the-setup-wizard) and delve deeper into writing stories.

Now that you installed Storybook successfully, let’s take a look at a story that was written for us.
> Source: https://storybook.js.org/docs/get-started/install
---

# Storybook for Angular

Storybook for Angular is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [Angular](https://angular.io/) applications. It uses Angular builders and integrates with [Compodoc](https://compodoc.app/) to provide automatic documentation generation.

## Install

To install Storybook in an existing Angular project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```sh
ng run <your-project>:storybook
```

To build Storybook, run:

```sh
ng run <your-project>:build-storybook
```

You will find the output in the configured `outputDir` (default is `dist/storybook/<your-project>`).

## Configure

To make the most out of Storybook in your Angular project, you can set up Compodoc integration and Storybook [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) based on your project needs.

### Compodoc

You can include JSDoc comments above components, directives, and other parts of your Angular code to include documentation for those elements. Compodoc uses these comments to [generate documentation](https://storybook.js.org/docs/writing-docs/autodocs.md) for your application. In Storybook, it is useful to add explanatory comments above `@Inputs` and `@Outputs`, since these are the main elements that Storybook displays in its user interface. The `@Inputs` and `@Outputs` are elements you can interact with in Storybook, such as [controls](https://storybook.js.org/docs/essentials/controls.md).

#### Automatic setup

When installing Storybook via `npx storybook@latest init`, you can set up Compodoc automatically.

#### Manual setup

If you have already installed Storybook, you can set up Compodoc manually.

Install the following dependencies:

```sh
npm install --save-dev @compodoc/compodoc
```

Add the following option to your Storybook Builder:

```jsonc title="angular.json"
{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular:start-storybook",
          "options": {
            // 👇 Add these
            "compodoc": true,
            "compodocArgs": [
              "-e",
              "json",
              "-d",
              // Where to store the generated documentation. It's usually the root of your Angular project. It's not necessarily the root of your Angular Workspace!
              ".",
            ],
          },
        },
        "build-storybook": {
          "builder": "@storybook/angular:build-storybook",
          "options": {
            // 👇 Add these
            "compodoc": true,
            "compodocArgs": ["-e", "json", "-d", "."],
          },
        },
      },
    },
  },
}
```

Go to your `.storybook/preview.ts` and add the following:

### Application-wide providers

If your component relies on application-wide providers, like the ones defined by [`BrowserAnimationsModule`](https://angular.dev/api/platform-browser/animations/BrowserAnimationsModule) or any other modules that use the forRoot pattern to provide a [`ModuleWithProviders`](https://angular.dev/api/core/ModuleWithProviders), you can apply the `applicationConfig` [decorator](https://storybook.js.org/docs/writing-stories/decorators.md) to all stories for that component. This will provide them with the [bootstrapApplication function](https://angular.dev/api/platform-browser/bootstrapApplication), used to bootstrap the component in Storybook.

### Angular dependencies

If your component has dependencies on other Angular directives and modules, these can be supplied using the `moduleMetadata` [decorator](https://storybook.js.org/docs/writing-stories/decorators.md) either for all stories of a component or for individual stories.

```ts title="YourComponent.stories.ts"

const meta: Meta<YourComponent> = {
  component: YourComponent,
  decorators: [
    // Apply metadata to all stories
    moduleMetadata({
      // import necessary ngModules or standalone components
      imports: [...],
      // declare components that are used in the template
      declarations: [...],
      // List of providers that should be available to the root component and all its children.
      providers: [...],
    }),
  ],
};
export default meta;
type Story = StoryObj<YourComponent>;

export const Base: Story = {};

export const WithCustomProvider: Story = {
  decorators: [
    // Apply metadata to a specific story
    moduleMetadata({
      imports: [...],
      declarations: [...],
      providers: [...],
    }),
  ],
};
```

## FAQ

### How do I manually install the Angular framework?

The easiest way to install the Angular framework is to run the upgrade command, but you can also set it up manually. First, install the framework:

Then, update your `.storybook/main.js|ts` to change the framework property:

Finally, update your `angular.json` to include the Storybook builder:

```jsonc title="angular.json"
{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular:start-storybook",
          "options": {
            // The path to the storybook config directory
            "configDir": ".storybook",
            // The build target of your project
            "browserTarget": "your-project:build",
            // The port you want to start Storybook on
            "port": 6006,
            // More options available, documented here:
            // https://github.com/storybookjs/storybook/tree/next/code/frameworks/angular/src/builders/start-storybook/schema.json
          },
        },
        "build-storybook": {
          "builder": "@storybook/angular:build-storybook",
          "options": {
            "configDir": ".storybook",
            "browserTarget": "your-project:build",
            "outputDir": "dist/storybook/your-project",
            // More options available, documented here:
            // https://github.com/storybookjs/storybook/tree/next/code/frameworks/angular/src/builders/build-storybook/schema.json
          },
        },
      },
    },
  },
}
```

### How do I migrate to an Angular Storybook builder?

The Storybook [Angular builder](https://angular.io/guide/glossary#builder) is a way to run Storybook in an Angular workspace. It is a drop-in replacement for running `storybook dev` and `storybook build` directly.

You can run `npx storybook@latest automigrate` to let Storybook detect and automatically fix your configuration. Otherwise, you can follow the next steps to adjust your configuration manually.

#### With a single project in your Angular workspace

Go to your `angular.json` and add `storybook` and `build-storybook` entries in your project's `architect` section, as shown [above](#manual-setup).

Then, adjust your `package.json` script section, to replace the existing Storybook scripts with the Angular CLI commands:

```diff title="package.json"
{
  "scripts": {
-    "storybook": "start-storybook -p 6006", // or `storybook dev -p 6006`
-    "build-storybook": "build-storybook" // or `storybook build`
+    "storybook": "ng run <project-name:storybook",
+    "storybook": "ng run <project-name:storybook",
  }
}
```

Note that `compodoc` is now built into `@storybook/angular`; you don't have to call it explicitly. If you were running `compodoc` in your `package.json` scripts, you can remove the related script:

```diff title="package.json"
{
  "scripts": {
-    "docs:json": "compodoc -p tsconfig.json -e json -d ./documentation",
-    "storybook": "npm run docs:json && start-storybook -p 6006",
-    "build-storybook": "npm run docs:json && build-storybook"
+    "storybook": "ng run <project-name:storybook",
+    "storybook": "ng run <project-name:storybook",
  }
}
```

#### With multiple projects in your Angular workspace

In case you have multiple projects, you will have to adjust your `angular.json` and `package.json` as described above for each project you want to use Storybook with. Please note that each project should have a dedicated `.storybook` folder placed at the project's root directory.

You can run `npx storybook@latest init` sequentially for each project to set up Storybook for each of them to automatically create the `.storybook` folder and create the necessary configuration in your `angular.json`.

You can then combine multiple Storybooks with [Storybook composition](https://storybook.js.org/docs/sharing/storybook-composition.md).

### How do I configure Angular's builder for Storybook?

These are common options you may need for the Angular builder:

| Configuration element        | Description                                                                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"browserTarget"`            | Build target to be served using the following format. <br /> `"example-project:builder:config"`                                                                                             |
| `"debugWebpack"`             | Debug the Webpack configuration <br /> `"debugWebpack": true`                                                                                                                               |
| `"tsConfig"`                 | Location of the TypeScript configuration file relative to the current workspace. <br /> `"tsConfig": "./tsconfig.json"`.                                                                    |
| `"preserveSymlinks"`         | Do not use the real path when resolving modules. If true, symlinks are resolved to their real path; otherwise, they are resolved to their symlinked path. <br /> `"preserveSymlinks": true` |
| `"port"`                     | Port used by Storybook. <br /> `"port": 6006`                                                                                                                                               |
| `"host"`                     | Set up a custom host for Storybook. <br /> `"host": "http://my-custom-host"`                                                                                                                |
| `"configDir"`                | Storybook configuration directory location. <br /> `"configDir": ".storybook"`                                                                                                              |
| `"https"`                    | Starts Storybook with HTTPS enabled. <br /> `"https": true` <br /> Requires custom certificate information.                                                                                 |
| `"sslCa"`                    | Provides an SSL certificate authority. <br /> `"sslCa": "your-custom-certificate-authority"` <br /> Optional usage with `"https"`                                                           |
| `"sslCert"`                  | Provides an SSL certificate. <br /> `"sslCert": "your-custom-certificate"` <br /> Required for `https`                                                                                      |
| `"sslKey"`                   | Provides an SSL key to serve Storybook. <br /> `"sslKey": "your-ssl-key"`                                                                                                                   |
| `"smokeTest"`                | Exit Storybook after successful start. <br /> `"smokeTest": true`                                                                                                                           |
| `"ci"`                       | Starts Storybook in CI mode (skips interactive prompts and will not open browser window). <br /> `"ci": true`                                                                               |
| `"open"`                     | Whether to open Storybook automatically in the browser. <br /> `"open": true`                                                                                                               |
| `"quiet"`                    | Filters Storybook verbose build output. <br /> `"quiet": true`                                                                                                                              |
| `"enableProdMode"`           | Disable Angular's development mode, which turns off assertions and other checks within the framework. <br /> `"enableProdMode": true`                                                       |
| `"docs"`                     | Starts Storybook in [documentation mode](https://storybook.js.org/docs/writing-docs/build-documentation.md#preview-storybooks-documentation). <br /> `"docs": true`                                                |
| `"compodoc"`                 | Execute compodoc before. <br /> `"compodoc": true`                                                                                                                                          |
| `"compodocArgs"`             | Compodoc [options](https://compodoc.app/guides/options.html). Options `-p` with tsconfig path and `-d` with workspace root is always given. <br /> `"compodocArgs": ["-e", "json"]`         |
| `"styles"`                   | Provide the location of the [application's styles](https://storybook.js.org/docs/configure/styling-and-css.md#global-styles) to be used with Storybook. <br /> `"styles": ["src/styles.css", "src/styles.scss"]`   |
| `"stylePreprocessorOptions"` | Provides further customization for style preprocessors resolved to the workspace root. <br /> `"stylePreprocessorOptions": { "includePaths": ["src/styles"] }`                              |
| `"assets"`                   | List of static application assets. <br /> `"assets": ["src/assets"]`                                                                                                                        |
| `"initialPath"`              | URL path to be appended when visiting Storybook for the first time. <br /> `"initialPath": "docs/configure-your-project--docs"`                                                             |
| `"webpackStatsJson"`         | Write Webpack Stats JSON to disk. <br /> `"webpackStatsJson": true`                                                                                                                         |
| `"previewUrl"`               | Disables the default storybook preview and lets you use your own. <br /> `"previewUrl": "iframe.html"`                                                                                      |
| `"loglevel"`                 | Controls level of logging during build. Can be one of: [trace, debug, info (default), warn, error, silent]. <br /> `"loglevel": "info"`                                                     |
| `"sourceMap"`                | Configure [sourcemaps](https://angular.dev/reference/configs/workspace-config#source-map-configuration.). <br /> `"sourceMap": true`                                                        |
| `"experimentalZoneless"`     | Configure [zoneless change detection](https://angular.dev/guide/zoneless). <br /> `"experimentalZoneless": true`                                                                            |

The full list of options can be found in the Angular builder schemas:

- [Build Storybook](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/build-schema.json)
- [Start Storybook](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/start-schema.json)

## API

### Options

You can pass an options object for additional configuration if needed:

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Webpack builder docs](https://storybook.js.org/docs/builders/webpack.md).
> Source: https://storybook.js.org/docs/get-started/frameworks/angular
---

# Storybook for Next.js with Vite

Storybook for Next.js (Vite) is the **recommended** [framework](https://storybook.js.org/docs/contribute/framework.md) for developing and testing UI components in isolation for [Next.js](https://nextjs.org/) applications. It uses [Vite](https://vitejs.dev/) for faster builds, better performance and [Storybook Testing](https://storybook.js.org/docs/writing-tests.md) support.

## Install

To install Storybook in an existing Next.js project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Choose between Vite and Webpack

This Vite-based framework offers several advantages over the Webpack-based [`@storybook/nextjs`](https://storybook.js.org/docs/get-started/frameworks/nextjs.md) framework, and is the recommended option:

- ⚡ **Faster builds** - Vite's build system is significantly faster than Webpack
- 🔧 **Modern tooling** - Uses the latest build tools and optimizations
- 🧪 **Better test support** - Full support for the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) and other testing features
- 📦 **Simpler configuration** - No need for Babel or complex Webpack configurations
- 🎯 **Better development experience** - Faster Hot Module Replacement and dev server startup

Storybook will automatically detect your project and select the `nextjs-vite` framework **unless** your project has custom Webpack or Babel configurations. If you have custom configurations, Storybook will ask you which framework to install.

Choose `nextjs-vite` if you're willing to migrate existing Babel or Webpack configurations to Vite. Choose `nextjs` (Webpack 5) if you need to keep your existing Webpack/Babel setup.

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Configure

Storybook for Next.js with Vite supports many Next.js features including:

- 🖼 [Image optimization](#nextjss-image-component)
- 🔤 [Font optimization](#nextjs-font-optimization)
- 🔀 [Routing and navigation](#nextjs-routing)
- 🌐 [`next/head`](#nextjs-head)
- ⤵️ [Absolute imports](#imports)
- 🎨 [Styling](#styling)
- 🎭 [Module mocking](#mocking-modules)
- ☁️ [React Server Component (experimental)](#react-server-components-rsc)

### Next.js's Image component

This framework allows you to use Next.js's [next/image](https://nextjs.org/docs/pages/api-reference/components/image) with no configuration.

#### Local images

[Local images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#local-images) are supported.

```jsx title="index.jsx"

function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      
      <p>Welcome to my homepage!</p>
    </>
  );
}
```

#### Remote images

[Remote images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#remote-images) are also supported.

```jsx title="index.jsx"

export default function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      
      <p>Welcome to my homepage!</p>
    </>
  );
}
```

### Next.js font optimization

[next/font](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts) is partially supported in Storybook. The packages `next/font/google` and `next/font/local` are supported.

#### `next/font/google`

You don't have to do anything. `next/font/google` is supported out of the box.

#### `next/font/local`

For local fonts you have to define the [src](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts#local-fonts) property.
The path is relative to the directory where the font loader function is called.

If the following component defines your localFont like this:

```js title="src/components/MyComponent.js"

const localRubikStorm = localFont({ src: './fonts/RubikStorm-Regular.ttf' });
```

The Vite-based framework automatically handles font path mapping, so you don't need to configure `staticDirs` for fonts like you would with the Webpack-based framework.

#### Not supported features of `next/font`

The following features are not supported (yet). Support for these features might be planned for the future:

- [Support font loaders configuration in next.config.js](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts#local-fonts)
- [fallback](https://nextjs.org/docs/pages/api-reference/components/font#fallback) option
- [adjustFontFallback](https://nextjs.org/docs/pages/api-reference/components/font#adjustfontfallback) option
- [preload](https://nextjs.org/docs/pages/api-reference/components/font#preload) option gets ignored. Storybook handles Font loading its own way.
- [display](https://nextjs.org/docs/pages/api-reference/components/font#display) option gets ignored. All fonts are loaded with display set to "block" to make Storybook load the font properly.

#### Mocking fonts during testing

Occasionally fetching fonts from Google may fail as part of your Storybook build step. It is highly recommended to mock these requests, as those failures can cause your pipeline to fail as well. Next.js [supports mocking fonts](https://github.com/vercel/next.js/blob/725ddc7371f80cca273779d37f961c3e20356f95/packages/font/src/google/fetch-css-from-google-fonts.ts#L36) via a JavaScript module located where the env var `NEXT_FONT_GOOGLE_MOCKED_RESPONSES` references.

For example, using [GitHub Actions](https://www.chromatic.com/docs/github-actions):

```yaml title=".github/workflows/ci.yml"
- uses: chromaui/action@latest
  env:
    #👇 the location of mocked fonts to use
    NEXT_FONT_GOOGLE_MOCKED_RESPONSES: ${{ github.workspace }}/mocked-google-fonts.js
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    token: ${{ secrets.GITHUB_TOKEN }}
```

Your mocked fonts will look something like this:

```js title="mocked-google-fonts.js"
//👇 Mocked responses of google fonts with the URL as the key
module.exports = {
  'https://fonts.googleapis.com/css?family=Inter:wght@400;500;600;800&display=block': `
    /* cyrillic-ext */
    @font-face {
      font-family: 'Inter';
      font-style: normal;
      font-weight: 400;
      font-display: block;
      src: url(https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZJhiJ-Ek-_EeAmM.woff2) format('woff2');
      unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
    }
    /* more font declarations go here */
    /* latin */
    @font-face {
      font-family: 'Inter';
      font-style: normal;
      font-weight: 400;
      font-display: block;
      src: url(https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2) format('woff2');
      unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
    }`,
};
```

### Next.js routing

[Next.js's router](https://nextjs.org/docs/pages/building-your-application/routing) is automatically stubbed for you so that when the router is interacted with, all of its interactions are automatically logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

You should only use `next/router` in the `pages` directory. In the `app` directory, it is necessary to use `next/navigation`.

#### Overriding defaults

Per-story overrides can be done by adding a `nextjs.router` property onto the story [parameters](https://storybook.js.org/docs/writing-stories/parameters.md). The framework will shallowly merge whatever you put here into the router.

```ts
// RouterBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

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

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

// Interact with the links to see the route change events in the Actions panel.
export const Example: Story = {
  parameters: {
    nextjs: {
      router: {
        pathname: '/profile/[id]',
        asPath: '/profile/1',
        query: {
          id: '1',
        },
      },
    },
  },
};
```

```ts
// RouterBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: RouterBasedComponent,
});

// Interact with the links to see the route change events in the Actions panel.
export const Example = meta.story({
  parameters: {
    nextjs: {
      router: {
        pathname: '/profile/[id]',
        asPath: '/profile/1',
        query: {
          id: '1',
        },
      },
    },
  },
});
```

These overrides can also be applied to [all stories for a component](https://storybook.js.org/docs/api/parameters.md#meta-parameters) or [all stories in your project](https://storybook.js.org/docs/api/parameters.md#project-parameters). Standard [parameter inheritance](https://storybook.js.org/docs/api/parameters.md#parameter-inheritance) rules apply.

#### Default router

The default values on the stubbed router are as follows (see [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals) for more details on how globals work).

```ts
// Default router
const defaultRouter = {
  // The locale should be configured globally: https://storybook.js.org/docs/essentials/toolbars-and-globals#globals
  locale: globals?.locale,
  asPath: '/',
  basePath: '/',
  isFallback: false,
  isLocaleDomain: false,
  isReady: true,
  isPreview: false,
  route: '/',
  pathname: '/',
  query: {},
};
```

Additionally, the [`router` object](https://nextjs.org/docs/pages/api-reference/functions/use-router#router-object) contains all of the original methods (such as `push()`, `replace()`, etc.) as mock functions that can be manipulated and asserted on using [regular mock APIs](https://vitest.dev/api/mock.html).

To override these defaults, you can use [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) and [`beforeEach`](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#setting-up-and-cleaning-up):

```ts
// .storybook/preview.tsx — CSF 3
// Replace your-framework with nextjs or nextjs-vite

export default {
  parameters: {
    nextjs: {
      // 👇 Override the default router properties
      router: {
        basePath: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default router method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
};
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

const preview = definePreview({
  parameters: {
    nextjs: {
      // 👇 Override the default router properties
      router: {
        basePath: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default router method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
});

export default preview;
```

### Next.js navigation

Please note that [`next/navigation`](https://nextjs.org/docs/app/building-your-application/routing) can only be used in components/pages in the `app` directory.

#### Set `nextjs.appDirectory` to `true`

If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true` in for that component's stories:

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true, // 👈 Set this
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true, // 👈 Set this
    },
  },
});
```

If your Next.js project uses the `app` directory for every page (in other words, it does not have a `pages` directory), you can set the parameter `nextjs.appDirectory` to `true` in the [`.storybook/preview.tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file to apply it to all stories.

```ts
// .storybook/preview.tsx — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const preview: Preview = {
  // ...
  parameters: {
    // ...
    nextjs: {
      appDirectory: true,
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default definePreview({
  // ...
  parameters: {
    // ...
    nextjs: {
      appDirectory: true,
    },
  },
});
```

#### Overriding defaults

Per-story overrides can be done by adding a `nextjs.navigation` property onto the story [parameters](https://storybook.js.org/docs/writing-stories/parameters.md). The framework will shallowly merge whatever you put here into the router.

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;

type Story = StoryObj<typeof meta>;

// Interact with the links to see the route change events in the Actions panel.
export const Example: Story = {
  parameters: {
    nextjs: {
      navigation: {
        pathname: '/profile',
        query: {
          user: '1',
        },
      },
    },
  },
};
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
    },
  },
});

// Interact with the links to see the route change events in the Actions panel.
export const Example = meta.story({
  parameters: {
    nextjs: {
      navigation: {
        pathname: '/profile',
        query: {
          user: '1',
        },
      },
    },
  },
});
```

These overrides can also be applied to [all stories for a component](https://storybook.js.org/docs/api/parameters.md#meta-parameters) or [all stories in your project](https://storybook.js.org/docs/api/parameters.md#project-parameters). Standard [parameter inheritance](https://storybook.js.org/docs/api/parameters.md#parameter-inheritance) rules apply.

#### `useSelectedLayoutSegment`, `useSelectedLayoutSegments`, and `useParams` hooks

The `useSelectedLayoutSegment`, `useSelectedLayoutSegments`, and `useParams` hooks are supported in Storybook. You have to set the `nextjs.navigation.segments` parameter to return the segments or the params you want to use.

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: ['dashboard', 'analytics'],
      },
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: ['dashboard', 'analytics'],
      },
    },
  },
});
```

With the above configuration, the component rendered in the stories would receive the following values from the hooks:

```js title="NavigationBasedComponent.js"

export default function NavigationBasedComponent() {
  const segment = useSelectedLayoutSegment(); // dashboard
  const segments = useSelectedLayoutSegments(); // ["dashboard", "analytics"]
  const params = useParams(); // {}
  // ...
}
```

To use `useParams`, you have to use a segments array where each element is an array containing two strings. The first string is the param key and the second string is the param value.

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: [
          ['slug', 'hello'],
          ['framework', 'nextjs'],
        ],
      },
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: [
          ['slug', 'hello'],
          ['framework', 'nextjs'],
        ],
      },
    },
  },
});
```

With the above configuration, the component rendered in the stories would receive the following values from the hooks:

```js title="ParamsBasedComponent.js"

export default function ParamsBasedComponent() {
  const segment = useSelectedLayoutSegment(); // hello
  const segments = useSelectedLayoutSegments(); // ["hello", "nextjs"]
  const params = useParams(); // { slug: "hello", framework: "nextjs" }
  ...
}
```

These overrides can also be applied to [a single story](https://storybook.js.org/docs/api/parameters.md#story-parameters) or [all stories in your project](https://storybook.js.org/docs/api/parameters.md#project-parameters). Standard [parameter inheritance](https://storybook.js.org/docs/api/parameters.md#parameter-inheritance) rules apply.

The default value of `nextjs.navigation.segments` is `[]` if not set.

#### Default navigation context

The default values on the stubbed navigation context are as follows:

```ts
// Default navigation context
const defaultNavigationContext = {
  pathname: '/',
  query: {},
};
```

Additionally, the [`router` object](https://nextjs.org/docs/app/api-reference/functions/use-router#userouter) contains all of the original methods (such as `push()`, `replace()`, etc.) as mock functions that can be manipulated and asserted on using [regular mock APIs](https://vitest.dev/api/mock.html).

To override these defaults, you can use [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) and [`beforeEach`](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#setting-up-and-cleaning-up):

```ts
// .storybook/preview.tsx — CSF 3
// Replace your-framework with nextjs or nextjs-vite

export default {
  parameters: {
    nextjs: {
      // 👇 Override the default navigation properties
      navigation: {
        pathname: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default navigation method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
};
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

const preview = definePreview({
  parameters: {
    nextjs: {
      // 👇 Override the default navigation properties
      navigation: {
        pathname: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default navigation method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
});

export default preview;
```

### Next.js Head

[`next/head`](https://nextjs.org/docs/pages/api-reference/components/head) is supported out of the box. You can use it in your stories like you would in your Next.js application. Please keep in mind, that the Head `children` are placed into the head element of the iframe that Storybook uses to render your stories.

## Next.js styling

### Sass/Scss

[Global Sass/SCSS stylesheets](https://nextjs.org/docs/pages/building-your-application/styling/sass) are also supported without any additional configuration. Just import them into [the preview config file](https://storybook.js.org/docs/configure/index.md#configure-story-rendering).

```ts
// .storybook/preview.tsx

```

This will automatically include any of your [custom Sass configurations](https://nextjs.org/docs/pages/building-your-application/styling/sass#customizing-sass-options) in your Next.js config file.

```ts
// next.config.ts

const config: NextConfig = {
  // Any options here are included in Sass compilation for your stories
  sassOptions: {
    includePaths: [path.join(process.cwd(), 'styles')],
  },
};

export default config;
```

### CSS/Sass/Scss Modules

[CSS modules](https://nextjs.org/docs/pages/building-your-application/styling/css-modules) work as expected.

```ts
// src/components/Button.ts
// This import will work in Storybook

// Sass/Scss modules are also supported
// import styles from './Button.module.scss'
// import styles from './Button.module.sass'

export function Button() {
  return (
    <button type="button" className={styles.error}>
      Destroy
    </button>
  );
}
```

### Styled JSX

The built-in CSS-in-JS solution for Next.js is [styled-jsx](https://nextjs.org/docs/pages/building-your-application/styling/css-in-js), and this framework supports that out of the box, too, with zero config.

```ts
// src/components/HelloWorld.ts
// This will work in Storybook
function HelloWorld() {
  return (
    <div>
      Hello world
      <p>scoped!</p>
      <style jsx>{`
        p {
          color: blue;
        }
        div {
          background: red;
        }
        @media (max-width: 600px) {
          div {
            background: blue;
          }
        }
      `}</style>
      <style global jsx>{`
        body {
          background: black;
        }
      `}</style>
    </div>
  );
}

export default HelloWorld;
```

### Tailwind

Tailwind in Next.js [is supported via PostCSS](https://nextjs.org/docs/app/getting-started/css#tailwind-css). Storybook will automatically handle the PostCSS config for you, including any custom PostCSS configuration, so that you can import your global CSS directly into [the preview config file](https://storybook.js.org/docs/configure/index.md#configure-story-rendering):

```ts
// .storybook/preview.tsx

```

### PostCSS

Next.js lets you [customize PostCSS config](https://nextjs.org/docs/pages/building-your-application/configuring/post-css). Thus this framework will automatically handle your PostCSS config for you.

### Imports

#### Absolute imports

[Absolute imports](https://nextjs.org/docs/pages/building-your-application/configuring/absolute-imports-and-module-aliases#absolute-imports) from the root directory are supported.

```jsx title="index.tsx"
// All good!

// Also good!

export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      
    </>
  );
}
```

Also OK for global styles in `.storybook/preview.tsx`!

```js title=".storybook/preview.tsx"

// ...
```

Absolute imports **cannot** be mocked in stories/tests. See the [Mocking modules](#mocking-modules) section for more information.

#### Module aliases

[Module aliases](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases#module-aliases) are also supported.

```jsx title="index.tsx"
// All good!

// Also good!

export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      
    </>
  );
}
```

#### Subpath imports

As an alternative to [module aliases](#module-aliases), you can use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) to import modules. This follows Node package standards and has benefits when [mocking modules](#mocking-modules).

To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for all modules in the project:

```json title="package.json"
{
  "imports": {
    "#*": ["./*", "./*.ts", "./*.tsx"]
  }
}
```

Because subpath imports replace module aliases, you can remove the path aliases from your TypeScript configuration.

Which can then be used like this:

```jsx title="index.tsx"

export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      
    </>
  );
}
```

### Mocking modules

Components often depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to [mock those modules](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md) to control and assert their behavior.

#### Built-in mocked modules

This framework provides mocks for many of Next.js' internal modules:

1. [`@storybook/nextjs-vite/cache.mock`](#storybooknextjs-vitecachemock)
2. [`@storybook/nextjs-vite/headers.mock`](#storybooknextjs-viteheadersmock)
3. [`@storybook/nextjs-vite/navigation.mock`](#storybooknextjs-vitenavigationmock)
4. [`@storybook/nextjs-vite/router.mock`](#storybooknextjs-viteroutermock)

#### Mocking other modules

To mock other modules, use [automocking](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#automocking) or one of the [alternative methods](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#alternative-methods) documented in the mocking modules guide.

### Runtime config

Next.js allows for [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration) which lets you import a handy `getConfig` function to get certain configuration defined in your `next.config.js` file at runtime.

In the context of Storybook with this framework, you can expect Next.js's [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration) feature to work just fine.

Note, because Storybook doesn't server render your components, your components will only see what they normally see on the client side (i.e. they won't see `serverRuntimeConfig` but will see `publicRuntimeConfig`).

For example, consider the following Next.js config:

```js title="next.config.js"
module.exports = {
  serverRuntimeConfig: {
    mySecret: 'secret',
    secondSecret: process.env.SECOND_SECRET, // Pass through env variables
  },
  publicRuntimeConfig: {
    staticFolder: '/static',
  },
};
```

Calls to `getConfig` would return the following object when called within Storybook:

```jsonc
// Runtime config
{
  "serverRuntimeConfig": {},
  "publicRuntimeConfig": {
    "staticFolder": "/static",
  },
}
```

### Custom Vite configuration

You can customize the [Vite configuration](https://storybook.js.org/docs/builders/vite.md#configuration) used by Storybook in your `.storybook/main.js|ts` file. By default, Storybook's configuration extends the Vite configuration used by your project, but you can configure it to not do so.

Not all Vite modifications are copy/paste-able between `next.config.js` and `.storybook/main.js|ts`. It is recommended to do your research on how to properly make your modification to Storybook's Vite config and on how [Vite works](https://vitejs.dev/guide/).

### Typescript

Storybook handles most [Typescript](https://www.typescriptlang.org/) configurations, but this framework adds additional support for Next.js's support for [Absolute Imports and Module path aliases](https://nextjs.org/docs/pages/building-your-application/configuring/absolute-imports-and-module-aliases). In short, it takes into account your `tsconfig.json`'s [baseUrl](https://www.typescriptlang.org/tsconfig#baseUrl) and [paths](https://www.typescriptlang.org/tsconfig#paths). Thus, a `tsconfig.json` like the one below would work out of the box.

```json title="tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}
```

### React Server Components (RSC)

(⚠️ **Experimental**)

If your app uses [React Server Components (RSC)](https://nextjs.org/docs/app/building-your-application/rendering/server-components), Storybook can render them in stories in the browser.

To enable this set the `experimentalRSC` feature flag in your `.storybook/main.js|ts` config:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  features: {
    experimentalRSC: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  features: {
    experimentalRSC: true,
  },
});
```

Setting this flag automatically wraps your story in a [Suspense](https://react.dev/reference/react/Suspense) wrapper, which is able to render asynchronous components in NextJS's version of React.

If this wrapper causes problems in any of your existing stories, you can selectively disable it using the `react.rsc` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) at the global/component/story level:

```ts
// MyServerComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: MyServerComponent,
  parameters: {
    react: { rsc: false },
  },
} satisfies Meta<typeof MyServerComponent>;
export default meta;
```

```ts
// MyServerComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: MyServerComponent,
  parameters: {
    react: { rsc: false },
  },
});
```

Note that wrapping your server components in Suspense does not help if your server components access server-side resources like the file system or Node-specific libraries. To work around this, you'll need to mock out your data access layer using [Vite aliases](https://vitejs.dev/config/shared-options.html#resolve-alias) or an addon like [storybook-addon-module-mock](https://storybook.js.org/addons/storybook-addon-module-mock).

If your server components access data via the network, we recommend using the [MSW Storybook Addon](https://storybook.js.org/addons/msw-storybook-addon) to mock network requests.

In the future we will provide better mocking support in Storybook and support for [Server Actions](https://nextjs.org/docs/app/api-reference/functions/server-actions).

## FAQ

### How do I migrate from the `nextjs` (Webpack 5) addon?

#### Automatic migration

Storybook provides a migration tool for migrating to this framework from the Webpack-based Next.js framework, [`@storybook/nextjs`](https://storybook.js.org/docs/get-started/frameworks/nextjs.md). To migrate, run this command:

```bash
npx storybook automigrate nextjs-to-nextjs-vite
```

This automigration tool performs the following actions:

1. Updates `package.json` files to replace `@storybook/nextjs` with `@storybook/nextjs-vite`
2. Updates `.storybook/main.js|ts` to change the framework property
3. Scans and updates import statements in your story files and configuration files

If your project has custom Webpack configurations in `.storybook/main.js|ts` (via `webpackFinal`), you'll need to migrate those to Vite configuration (via `viteFinal`) after running this automigration. See the [Vite builder documentation](https://storybook.js.org/docs/builders/vite.md#migrating-from-webpack) for more information.

#### Manual migration

First, install the framework:

```shell
npm install --save-dev @storybook/nextjs-vite
```

```shell
pnpm add --save-dev @storybook/nextjs-vite
```

```shell
yarn add --dev @storybook/nextjs-vite
```

Then, update your `.storybook/main.js|ts` to change the framework property:

```diff
// .storybook/main.ts — CSF 3
- import type { StorybookConfig } from '@storybook/your-previous-framework';
+ import type { StorybookConfig } from '@storybook/nextjs-vite';

const config: StorybookConfig = {
  // ...
-  framework: '@storybook/react-webpack5',
+  framework: '@storybook/nextjs-vite',
};

export default config;
```

```diff
// .storybook/main.ts — CSF Next 🧪
- import { defineMain } from '@storybook/your-previous-framework/node';
+ import { defineMain } from '@storybook/nextjs-vite/node';

export default defineMain({
  // ...
-  framework: '@storybook/react-webpack5',
+  framework: '@storybook/nextjs-vite',
});
```

If your Storybook configuration contains custom Webpack operations in [`webpackFinal`](https://storybook.js.org/docs/api/main-config/main-config-webpack-final.md), you will likely need to create equivalents in [`viteFinal`](https://storybook.js.org/docs/api/main-config/main-config-vite-final.md).

For more information, see the [Vite builder documentation](https://storybook.js.org/docs/builders/vite.md#migrating-from-webpack).

Finally, if you were using Storybook plugins to integrate with Next.js, those are no longer necessary when using this framework and can be removed:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  addons: [
    // ...
    // 👇 These can both be removed
    // 'storybook-addon-next',
    // 'storybook-addon-next-router',
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  addons: [
    // ...
    // 👇 These can both be removed
    // 'storybook-addon-next',
    // 'storybook-addon-next-router',
  ],
});
```

### Stories for pages/components which fetch data

Next.js pages can fetch data directly within server components in the `app` directory, which often include module imports that only run in a node environment. This does not (currently) work within Storybook, because if you import from a Next.js page file containing those node module imports in your stories, your Storybook's Vite build will crash because those modules will not run in a browser. To get around this, you can extract the component in your page file into a separate file and import that pure component in your stories. Or, if that's not feasible for some reason, you can [configure Vite to handle those modules](https://vitejs.dev/config/dep-optimization-options.html#optimizedeps-exclude) in your Storybook's [`viteFinal` configuration](https://storybook.js.org/docs/builders/vite.md#configuration).

**Before**

```jsx title="app/my-page/index.jsx"
async function getData() {
  const res = await fetch(...);
  // ...
}

// Using this component in your stories will break the Storybook build
export default async function Page() {
  const data = await getData();

  return // ...
}
```

**After**

```jsx title="app/my-page/index.jsx"
// Use this component in your stories

async function getData() {
  const res = await fetch(...);
  // ...
}

export default async function Page() {
  const data = await getData();

  return ;
}
```

### Statically imported images won't load

Make sure you are treating image imports the same way you treat them when using `next/image` in normal development.

Before using this framework, image imports would import the raw path to the image (e.g. `'static/media/stories/assets/logo.svg'`). Now image imports work the "Next.js way", meaning that you now get an object when importing an image. For example:

```jsonc
// Image import object
{
  "src": "static/media/stories/assets/logo.svg",
  "height": 48,
  "width": 48,
  "blurDataURL": "static/media/stories/assets/logo.svg",
}
```

Therefore, if something in Storybook isn't showing the image properly, make sure you expect the object to be returned from an import instead of only the asset path.

See [local images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#local-images) for more detail on how Next.js treats static image imports.

### Error: You are importing avif images, but you don't have sharp installed. You have to install sharp in order to use image optimization features in Next.js.

`sharp` is a dependency of Next.js's image optimization feature. If you see this error, you need to install `sharp` in your project.

```bash
npm install sharp
```

```bash
yarn add sharp
```

```bash
pnpm add sharp
```

You can refer to the [Install `sharp` to Use Built-In Image Optimization](https://nextjs.org/docs/messages/install-sharp) in the Next.js documentation for more information.

### Should I use the Vite or Webpack version?

We recommend using `@storybook/nextjs-vite` (this framework) for most projects because it offers:

- Faster builds and development server startup
- Better support for modern testing features like the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md)
- Simpler configuration without Babel
- Better developer experience with faster HMR

However, if your project has custom Webpack configurations that are incompatible with Vite, or you need specific Webpack features, you should use [`@storybook/nextjs`](https://storybook.js.org/docs/get-started/frameworks/nextjs.md) (Webpack 5) instead.

## API

### Modules

The `@storybook/nextjs-vite` package exports several modules that enable you to [mock](#mocking-modules) Next.js's internal behavior.

#### `@storybook/nextjs-vite/cache.mock`

Type: `typeof import('next/cache')`

This module exports mocked implementations of the `next/cache` module's exports. You can use it to create your own mock implementations or assert on mock calls in a story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

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

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

export const Submitted: Story = {
  async play({ canvas, userEvent }) {
    const submitButton = canvas.getByRole('button', { name: /submit/i });
    await userEvent.click(saveButton);
    // 👇 Use any mock assertions on the function
    await expect(revalidatePath).toHaveBeenCalledWith('/');
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
});

export const Submitted = meta.story({
  async play({ canvas, userEvent }) {
    const submitButton = canvas.getByRole('button', { name: /submit/i });
    await userEvent.click(saveButton);
    // 👇 Use any mock assertions on the function
    await expect(revalidatePath).toHaveBeenCalledWith('/');
  },
});
```

#### `@storybook/nextjs-vite/headers.mock`

Type: [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies#cookiessetname-value-options), [`headers`](https://nextjs.org/docs/app/api-reference/functions/headers) and [`draftMode`](https://nextjs.org/docs/app/api-reference/functions/draft-mode) from Next.js

This module exports _writable_ mocked implementations of the `next/headers` module's exports. You can use it to set up cookies or headers that are read in your story, and to later assert that they have been called.

Next.js's default [`headers()`](https://nextjs.org/docs/app/api-reference/functions/headers) export is read-only, but this module exposes methods allowing you to write to the headers:

- **`headers().append(name: string, value: string)`**: Appends the value to the header if it exists already.
- **`headers().delete(name: string)`**: Deletes the header
- **`headers().set(name: string, value: string)`**: Sets the header to the value provided.

For cookies, you can use the existing API to write them. E.g., `cookies().set('firstName', 'Jane')`.

Because `headers()`, `cookies()` and their sub-functions are all mocks you can use any [mock utilities](https://vitest.dev/api/mock.html) in your stories, like `headers().getAll.mock.calls`.

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

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

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

export const LoggedInEurope: Story = {
  async beforeEach() {
    // 👇 Set mock cookies, headers and draft mode ahead of rendering
    cookies().set('username', 'Sol');
    headers().set('timezone', 'Central European Summer Time');
    draftMode.mockReturnValue({
      isEnabled: true,
      enable: fn(),
      disable: fn(),
    });
  },
  async play() {
    // 👇 Assert that your component called the mocks
    await expect(cookies().get).toHaveBeenCalledOnce();
    await expect(cookies().get).toHaveBeenCalledWith('username');
    await expect(headers().get).toHaveBeenCalledOnce();
    await expect(headers().get).toHaveBeenCalledWith('timezone');
    await expect(draftMode).toHaveBeenCalled();
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
});

export const LoggedInEurope = meta.story({
  async beforeEach() {
    // 👇 Set mock cookies, headers and draft mode ahead of rendering
    cookies().set('username', 'Sol');
    headers().set('timezone', 'Central European Summer Time');
    draftMode.mockReturnValue({
      isEnabled: true,
      enable: fn(),
      disable: fn(),
    });
  },
  async play() {
    // 👇 Assert that your component called the mocks
    await expect(cookies().get).toHaveBeenCalledOnce();
    await expect(cookies().get).toHaveBeenCalledWith('username');
    await expect(headers().get).toHaveBeenCalledOnce();
    await expect(headers().get).toHaveBeenCalledWith('timezone');
    await expect(draftMode).toHaveBeenCalled();
  },
});
```

#### `@storybook/nextjs-vite/navigation.mock`

Type: `typeof import('next/navigation') & getRouter: () => ReturnType<typeof import('next/navigation')['useRouter']>`

This module exports mocked implementations of the `next/navigation` module's exports. It also exports a `getRouter` function that returns a mocked version of [Next.js's `router` object from `useRouter`](https://nextjs.org/docs/app/api-reference/functions/use-router#userouter), allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

const meta = {
  component: MyForm,
  parameters: {
    nextjs: {
      // 👇 As in the Next.js application, next/navigation only works using App Router
      appDirectory: true,
    },
  },
} satisfies Meta<typeof MyForm>;

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

export const Unauthenticated: Story = {
  async play() {
    // 👇 Assert that your component called redirect()
    await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
  },
};

export const GoBack: Story = {
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
  parameters: {
    nextjs: {
      // 👇 As in the Next.js application, next/navigation only works using App Router
      appDirectory: true,
    },
  },
});

export const Unauthenticated = meta.story({
  async play() {
    // 👇 Assert that your component called redirect()
    await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
  },
});

export const GoBack = meta.story({
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
});
```

#### `@storybook/nextjs-vite/router.mock`

Type: `typeof import('next/router') & getRouter: () => ReturnType<typeof import('next/router')['useRouter']>`

This module exports mocked implementations of the `next/router` module's exports. It also exports a `getRouter` function that returns a mocked version of [Next.js's `router` object from `useRouter`](https://nextjs.org/docs/pages/api-reference/functions/use-router#router-object), allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

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

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

export const GoBack: Story = {
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
});

export const GoBack = meta.story({
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
});
```

### Options

You can pass an options object for additional configuration if needed:

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  framework: {
    name: '@storybook/your-framework',
    options: {
      nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  framework: {
    name: '@storybook/your-framework',
    options: {
      nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
    },
  },
});
```

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For Next.js with Vite, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).

#### `image`

Type: `object`

Props to pass to every instance of `next/image`. See [next/image docs](https://nextjs.org/docs/pages/api-reference/components/image) for more details.

#### `nextConfigPath`

Type: `string`

The absolute path to the `next.config.js` file. This is necessary if you have a custom `next.config.js` file that is not in the root directory of your project.

### Parameters

This framework contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `nextjs` namespace:

#### `appDirectory`

Type: `boolean`

Default: `false`

If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true`. Because this is a parameter, you can apply it to a [single story](https://storybook.js.org/docs/api/parameters.md#story-parameters), [all stories for a component](https://storybook.js.org/docs/api/parameters.md#meta-parameters), or [every story in your Storybook](https://storybook.js.org/docs/api/parameters.md#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.

#### `navigation`

Type:

```ts
{
  asPath?: string;
  pathname?: string;
  query?: Record<string, string>;
  segments?: (string | [string, string])[];
}
```

Default value:

```js
{
  segments: [];
}
```

The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.

#### `router`

Type:

```ts
{
  asPath?: string;
  pathname?: string;
  query?: Record<string, string>;
}
```

The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
> Source: https://storybook.js.org/docs/get-started/frameworks/nextjs-vite
---

# Storybook for Next.js with Webpack

Storybook for Next.js (Webpack) is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [Next.js](https://nextjs.org/) applications using [Webpack 5](https://webpack.js.org/).

**We recommend using [`@storybook/nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md)** for most Next.js projects. The Vite-based framework is faster, more modern, and offers better support for testing features.

Use this Webpack-based framework (`@storybook/nextjs`) only if:

- Your project has custom Webpack configurations that are incompatible with Vite
- Your project has custom Babel configurations that require Webpack
- You need specific Webpack features not available in Vite

## Install

To install Storybook in an existing Next.js project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

The command will prompt you to choose between this framework and [`@storybook/nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md). We recommend the Vite-based framework ([learn why](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md#choose-between-vite-and-webpack)).

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Configure

Storybook for Next.js supports many Next.js features including:

- 🖼 [Image optimization](#nextjss-image-component)
- 🔤 [Font optimization](#nextjs-font-optimization)
- 🔀 [Routing and navigation](#nextjs-routing)
- 🌐 [`next/head`](#nextjs-head)
- ⤵️ [Absolute imports](#imports)
- 🎨 [Styling](#styling)
- 🎭 [Module mocking](#mocking-modules)
- ☁️ [React Server Component (experimental)](#react-server-components-rsc)

### Next.js's Image component

This framework allows you to use Next.js's [next/image](https://nextjs.org/docs/pages/api-reference/components/image) with no configuration.

#### Local images

[Local images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#local-images) are supported.

```jsx title="index.jsx"

function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      
      <p>Welcome to my homepage!</p>
    </>
  );
}
```

#### Remote images

[Remote images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#remote-images) are also supported.

```jsx title="index.jsx"

export default function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      
      <p>Welcome to my homepage!</p>
    </>
  );
}
```

### Next.js font optimization

[next/font](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts) is partially supported in Storybook. The packages `next/font/google` and `next/font/local` are supported.

#### `next/font/google`

You don't have to do anything. `next/font/google` is supported out of the box.

#### `next/font/local`

For local fonts you have to define the [src](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts#local-fonts) property.
The path is relative to the directory where the font loader function is called.

If the following component defines your localFont like this:

```js title="src/components/MyComponent.js"

const localRubikStorm = localFont({ src: './fonts/RubikStorm-Regular.ttf' });
```

##### `staticDir` mapping

You have to tell Storybook where the `fonts` directory is located, via the [`staticDirs` configuration](https://storybook.js.org/docs/api/main-config/main-config-static-dirs.md#with-configuration-objects). The `from` value is relative to the `.storybook` directory. The `to` value is relative to the execution context of Storybook. Very likely it is the root of your project.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  staticDirs: [
    {
      from: '../src/components/fonts',
      to: 'src/components/fonts',
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  staticDirs: [
    {
      from: '../src/components/fonts',
      to: 'src/components/fonts',
    },
  ],
});
```

#### Not supported features of `next/font`

The following features are not supported (yet). Support for these features might be planned for the future:

- [Support font loaders configuration in next.config.js](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts#local-fonts)
- [fallback](https://nextjs.org/docs/pages/api-reference/components/font#fallback) option
- [adjustFontFallback](https://nextjs.org/docs/pages/api-reference/components/font#adjustfontfallback) option
- [preload](https://nextjs.org/docs/pages/api-reference/components/font#preload) option gets ignored. Storybook handles Font loading its own way.
- [display](https://nextjs.org/docs/pages/api-reference/components/font#display) option gets ignored. All fonts are loaded with display set to "block" to make Storybook load the font properly.

#### Mocking fonts during testing

Occasionally fetching fonts from Google may fail as part of your Storybook build step. It is highly recommended to mock these requests, as those failures can cause your pipeline to fail as well. Next.js [supports mocking fonts](https://github.com/vercel/next.js/blob/725ddc7371f80cca273779d37f961c3e20356f95/packages/font/src/google/fetch-css-from-google-fonts.ts#L36) via a JavaScript module located where the env var `NEXT_FONT_GOOGLE_MOCKED_RESPONSES` references.

For example, using [GitHub Actions](https://www.chromatic.com/docs/github-actions):

```yaml title=".github/workflows/ci.yml"
- uses: chromaui/action@latest
  env:
    #👇 the location of mocked fonts to use
    NEXT_FONT_GOOGLE_MOCKED_RESPONSES: ${{ github.workspace }}/mocked-google-fonts.js
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    token: ${{ secrets.GITHUB_TOKEN }}
```

Your mocked fonts will look something like this:

```js title="mocked-google-fonts.js"
//👇 Mocked responses of google fonts with the URL as the key
module.exports = {
  'https://fonts.googleapis.com/css?family=Inter:wght@400;500;600;800&display=block': `
    /* cyrillic-ext */
    @font-face {
      font-family: 'Inter';
      font-style: normal;
      font-weight: 400;
      font-display: block;
      src: url(https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZJhiJ-Ek-_EeAmM.woff2) format('woff2');
      unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
    }
    /* more font declarations go here */
    /* latin */
    @font-face {
      font-family: 'Inter';
      font-style: normal;
      font-weight: 400;
      font-display: block;
      src: url(https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2) format('woff2');
      unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
    }`,
};
```

### Next.js routing

[Next.js's router](https://nextjs.org/docs/pages/building-your-application/routing) is automatically stubbed for you so that when the router is interacted with, all of its interactions are automatically logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

You should only use `next/router` in the `pages` directory. In the `app` directory, it is necessary to use `next/navigation`.

#### Overriding defaults

Per-story overrides can be done by adding a `nextjs.router` property onto the story [parameters](https://storybook.js.org/docs/writing-stories/parameters.md). The framework will shallowly merge whatever you put here into the router.

```ts
// RouterBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

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

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

// Interact with the links to see the route change events in the Actions panel.
export const Example: Story = {
  parameters: {
    nextjs: {
      router: {
        pathname: '/profile/[id]',
        asPath: '/profile/1',
        query: {
          id: '1',
        },
      },
    },
  },
};
```

```ts
// RouterBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: RouterBasedComponent,
});

// Interact with the links to see the route change events in the Actions panel.
export const Example = meta.story({
  parameters: {
    nextjs: {
      router: {
        pathname: '/profile/[id]',
        asPath: '/profile/1',
        query: {
          id: '1',
        },
      },
    },
  },
});
```

These overrides can also be applied to [all stories for a component](https://storybook.js.org/docs/api/parameters.md#meta-parameters) or [all stories in your project](https://storybook.js.org/docs/api/parameters.md#project-parameters). Standard [parameter inheritance](https://storybook.js.org/docs/api/parameters.md#parameter-inheritance) rules apply.

#### Default router

The default values on the stubbed router are as follows (see [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals) for more details on how globals work).

```ts
// Default router
const defaultRouter = {
  // The locale should be configured globally: https://storybook.js.org/docs/essentials/toolbars-and-globals#globals
  locale: globals?.locale,
  asPath: '/',
  basePath: '/',
  isFallback: false,
  isLocaleDomain: false,
  isReady: true,
  isPreview: false,
  route: '/',
  pathname: '/',
  query: {},
};
```

Additionally, the [`router` object](https://nextjs.org/docs/pages/api-reference/functions/use-router#router-object) contains all of the original methods (such as `push()`, `replace()`, etc.) as mock functions that can be manipulated and asserted on using [regular mock APIs](https://vitest.dev/api/mock.html).

To override these defaults, you can use [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) and [`beforeEach`](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#setting-up-and-cleaning-up):

```ts
// .storybook/preview.tsx — CSF 3
// Replace your-framework with nextjs or nextjs-vite

export default {
  parameters: {
    nextjs: {
      // 👇 Override the default router properties
      router: {
        basePath: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default router method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
};
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

const preview = definePreview({
  parameters: {
    nextjs: {
      // 👇 Override the default router properties
      router: {
        basePath: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default router method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
});

export default preview;
```

### Next.js navigation

Please note that [`next/navigation`](https://nextjs.org/docs/app/building-your-application/routing) can only be used in components/pages in the `app` directory.

#### Set `nextjs.appDirectory` to `true`

If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true` in for that component's stories:

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true, // 👈 Set this
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true, // 👈 Set this
    },
  },
});
```

If your Next.js project uses the `app` directory for every page (in other words, it does not have a `pages` directory), you can set the parameter `nextjs.appDirectory` to `true` in the [`.storybook/preview.tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file to apply it to all stories.

```ts
// .storybook/preview.tsx — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const preview: Preview = {
  // ...
  parameters: {
    // ...
    nextjs: {
      appDirectory: true,
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default definePreview({
  // ...
  parameters: {
    // ...
    nextjs: {
      appDirectory: true,
    },
  },
});
```

#### Overriding defaults

Per-story overrides can be done by adding a `nextjs.navigation` property onto the story [parameters](https://storybook.js.org/docs/writing-stories/parameters.md). The framework will shallowly merge whatever you put here into the router.

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;

type Story = StoryObj<typeof meta>;

// Interact with the links to see the route change events in the Actions panel.
export const Example: Story = {
  parameters: {
    nextjs: {
      navigation: {
        pathname: '/profile',
        query: {
          user: '1',
        },
      },
    },
  },
};
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
    },
  },
});

// Interact with the links to see the route change events in the Actions panel.
export const Example = meta.story({
  parameters: {
    nextjs: {
      navigation: {
        pathname: '/profile',
        query: {
          user: '1',
        },
      },
    },
  },
});
```

These overrides can also be applied to [all stories for a component](https://storybook.js.org/docs/api/parameters.md#meta-parameters) or [all stories in your project](https://storybook.js.org/docs/api/parameters.md#project-parameters). Standard [parameter inheritance](https://storybook.js.org/docs/api/parameters.md#parameter-inheritance) rules apply.

#### `useSelectedLayoutSegment`, `useSelectedLayoutSegments`, and `useParams` hooks

The `useSelectedLayoutSegment`, `useSelectedLayoutSegments`, and `useParams` hooks are supported in Storybook. You have to set the `nextjs.navigation.segments` parameter to return the segments or the params you want to use.

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: ['dashboard', 'analytics'],
      },
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: ['dashboard', 'analytics'],
      },
    },
  },
});
```

With the above configuration, the component rendered in the stories would receive the following values from the hooks:

```js title="NavigationBasedComponent.js"

export default function NavigationBasedComponent() {
  const segment = useSelectedLayoutSegment(); // dashboard
  const segments = useSelectedLayoutSegments(); // ["dashboard", "analytics"]
  const params = useParams(); // {}
  // ...
}
```

To use `useParams`, you have to use a segments array where each element is an array containing two strings. The first string is the param key and the second string is the param value.

```ts
// NavigationBasedComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: [
          ['slug', 'hello'],
          ['framework', 'nextjs'],
        ],
      },
    },
  },
} satisfies Meta<typeof NavigationBasedComponent>;
export default meta;
```

```ts
// NavigationBasedComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: NavigationBasedComponent,
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        segments: [
          ['slug', 'hello'],
          ['framework', 'nextjs'],
        ],
      },
    },
  },
});
```

With the above configuration, the component rendered in the stories would receive the following values from the hooks:

```js title="ParamsBasedComponent.js"

export default function ParamsBasedComponent() {
  const segment = useSelectedLayoutSegment(); // hello
  const segments = useSelectedLayoutSegments(); // ["hello", "nextjs"]
  const params = useParams(); // { slug: "hello", framework: "nextjs" }
  ...
}
```

These overrides can also be applied to [a single story](https://storybook.js.org/docs/api/parameters.md#story-parameters) or [all stories in your project](https://storybook.js.org/docs/api/parameters.md#project-parameters). Standard [parameter inheritance](https://storybook.js.org/docs/api/parameters.md#parameter-inheritance) rules apply.

The default value of `nextjs.navigation.segments` is `[]` if not set.

#### Default navigation context

The default values on the stubbed navigation context are as follows:

```ts
// Default navigation context
const defaultNavigationContext = {
  pathname: '/',
  query: {},
};
```

Additionally, the [`router` object](https://nextjs.org/docs/app/api-reference/functions/use-router#userouter) contains all of the original methods (such as `push()`, `replace()`, etc.) as mock functions that can be manipulated and asserted on using [regular mock APIs](https://vitest.dev/api/mock.html).

To override these defaults, you can use [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) and [`beforeEach`](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#setting-up-and-cleaning-up):

```ts
// .storybook/preview.tsx — CSF 3
// Replace your-framework with nextjs or nextjs-vite

export default {
  parameters: {
    nextjs: {
      // 👇 Override the default navigation properties
      navigation: {
        pathname: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default navigation method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
};
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

const preview = definePreview({
  parameters: {
    nextjs: {
      // 👇 Override the default navigation properties
      navigation: {
        pathname: '/app/',
      },
    },
  },
  async beforeEach() {
    // 👇 Manipulate the default navigation method mocks
    getRouter().push.mockImplementation(() => {
      /* ... */
    });
  },
});

export default preview;
```

### Next.js Head

[`next/head`](https://nextjs.org/docs/pages/api-reference/components/head) is supported out of the box. You can use it in your stories like you would in your Next.js application. Please keep in mind, that the Head `children` are placed into the head element of the iframe that Storybook uses to render your stories.

## Next.js styling

### Sass/Scss

[Global Sass/SCSS stylesheets](https://nextjs.org/docs/pages/building-your-application/styling/sass) are also supported without any additional configuration. Just import them into [the preview config file](https://storybook.js.org/docs/configure/index.md#configure-story-rendering).

```ts
// .storybook/preview.tsx

```

This will automatically include any of your [custom Sass configurations](https://nextjs.org/docs/pages/building-your-application/styling/sass#customizing-sass-options) in your Next.js config file.

```ts
// next.config.ts

const config: NextConfig = {
  // Any options here are included in Sass compilation for your stories
  sassOptions: {
    includePaths: [path.join(process.cwd(), 'styles')],
  },
};

export default config;
```

### CSS/Sass/Scss Modules

[CSS modules](https://nextjs.org/docs/pages/building-your-application/styling/css-modules) work as expected.

```ts
// src/components/Button.ts
// This import will work in Storybook

// Sass/Scss modules are also supported
// import styles from './Button.module.scss'
// import styles from './Button.module.sass'

export function Button() {
  return (
    <button type="button" className={styles.error}>
      Destroy
    </button>
  );
}
```

### Styled JSX

The built-in CSS-in-JS solution for Next.js is [styled-jsx](https://nextjs.org/docs/pages/building-your-application/styling/css-in-js), and this framework supports that out of the box, too, with zero config.

```ts
// src/components/HelloWorld.ts
// This will work in Storybook
function HelloWorld() {
  return (
    <div>
      Hello world
      <p>scoped!</p>
      <style jsx>{`
        p {
          color: blue;
        }
        div {
          background: red;
        }
        @media (max-width: 600px) {
          div {
            background: blue;
          }
        }
      `}</style>
      <style global jsx>{`
        body {
          background: black;
        }
      `}</style>
    </div>
  );
}

export default HelloWorld;
```

You can use your own Babel config, too. This is an example of how you can customize styled-jsx.

```jsonc
// .babelrc (or whatever config file you use)
{
  "presets": [
    [
      "next/babel",
      {
        "styled-jsx": {
          "plugins": ["@styled-jsx/plugin-sass"],
        },
      },
    ],
  ],
}
```

### Tailwind

Tailwind in Next.js [is supported via PostCSS](https://nextjs.org/docs/app/getting-started/css#tailwind-css). Storybook will automatically handle the PostCSS config for you, including any custom PostCSS configuration, so that you can import your global CSS directly into [the preview config file](https://storybook.js.org/docs/configure/index.md#configure-story-rendering):

```ts
// .storybook/preview.tsx

```

### PostCSS

Next.js lets you [customize PostCSS config](https://nextjs.org/docs/pages/building-your-application/configuring/post-css). Thus this framework will automatically handle your PostCSS config for you.

### Imports

#### Absolute imports

[Absolute imports](https://nextjs.org/docs/pages/building-your-application/configuring/absolute-imports-and-module-aliases#absolute-imports) from the root directory are supported.

```jsx title="index.tsx"
// All good!

// Also good!

export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      
    </>
  );
}
```

Also OK for global styles in `.storybook/preview.tsx`!

```js title=".storybook/preview.tsx"

// ...
```

Absolute imports **cannot** be mocked in stories/tests. See the [Mocking modules](#mocking-modules) section for more information.

#### Module aliases

[Module aliases](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases#module-aliases) are also supported.

```jsx title="index.tsx"
// All good!

// Also good!

export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      
    </>
  );
}
```

#### Subpath imports

As an alternative to [module aliases](#module-aliases), you can use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) to import modules. This follows Node package standards and has benefits when [mocking modules](#mocking-modules).

To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for all modules in the project:

```json title="package.json"
{
  "imports": {
    "#*": ["./*", "./*.ts", "./*.tsx"]
  }
}
```

Because subpath imports replace module aliases, you can remove the path aliases from your TypeScript configuration.

Which can then be used like this:

```jsx title="index.tsx"

export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      
    </>
  );
}
```

### Mocking modules

Components often depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to [mock those modules](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md) to control and assert their behavior.

#### Built-in mocked modules

This framework provides mocks for many of Next.js' internal modules:

1. [`@storybook/nextjs/cache.mock`](#storybooknextjscachemock)
2. [`@storybook/nextjs/headers.mock`](#storybooknextjsheadersmock)
3. [`@storybook/nextjs/navigation.mock`](#storybooknextjsnavigationmock)
4. [`@storybook/nextjs/router.mock`](#storybooknextjsroutermock)

#### Mocking other modules

To mock other modules, use [automocking](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#automocking) or one of the [alternative methods](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#alternative-methods) documented in the mocking modules guide.

### Runtime config

Next.js allows for [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration) which lets you import a handy `getConfig` function to get certain configuration defined in your `next.config.js` file at runtime.

In the context of Storybook with this framework, you can expect Next.js's [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration) feature to work just fine.

Note, because Storybook doesn't server render your components, your components will only see what they normally see on the client side (i.e. they won't see `serverRuntimeConfig` but will see `publicRuntimeConfig`).

For example, consider the following Next.js config:

```js title="next.config.js"
module.exports = {
  serverRuntimeConfig: {
    mySecret: 'secret',
    secondSecret: process.env.SECOND_SECRET, // Pass through env variables
  },
  publicRuntimeConfig: {
    staticFolder: '/static',
  },
};
```

Calls to `getConfig` would return the following object when called within Storybook:

```jsonc
// Runtime config
{
  "serverRuntimeConfig": {},
  "publicRuntimeConfig": {
    "staticFolder": "/static",
  },
}
```

### Custom Webpack config

Next.js comes with a lot of things for free out of the box like Sass support, but sometimes you add [custom Webpack config modifications to Next.js](https://nextjs.org/docs/pages/api-reference/next-config-js/webpack). This framework takes care of most of the Webpack modifications you would want to add. If Next.js supports a feature out of the box, then that feature will work out of the box in Storybook. If Next.js doesn't support something out of the box, but makes it easy to configure, then this framework will do the same for that thing for Storybook.

Any Webpack modifications desired for Storybook should be made in [`.storybook/main.js|ts`](https://storybook.js.org/docs/builders/webpack.md#override-the-default-configuration).

Note: Not all Webpack modifications are copy/paste-able between `next.config.js` and `.storybook/main.js|ts`. It is recommended to do your research on how to properly make your modification to Storybook's Webpack config and on how [Webpack works](https://webpack.js.org/concepts/).

Below is an example of how to add SVGR support to Storybook with this framework.

```ts
// .storybook/main.ts — CSF 3

const config: StorybookConfig = {
  // ...
  webpackFinal: async (config) => {
    config.module = config.module || {};
    config.module.rules = config.module.rules || [];

    // This modifies the existing image rule to exclude .svg files
    // since you want to handle those files with @svgr/webpack
    const imageRule = config.module.rules.find((rule) => rule?.['test']?.test('.svg'));
    if (imageRule) {
      imageRule['exclude'] = /\.svg$/;
    }

    // Configure .svg files to be loaded with @svgr/webpack
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    });

    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  webpackFinal: async (config) => {
    config.module = config.module || {};
    config.module.rules = config.module.rules || [];

    // This modifies the existing image rule to exclude .svg files
    // since you want to handle those files with @svgr/webpack
    const imageRule = config.module.rules.find((rule) => rule?.['test']?.test('.svg'));
    if (imageRule) {
      imageRule['exclude'] = /\.svg$/;
    }

    // Configure .svg files to be loaded with @svgr/webpack
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    });

    return config;
  },
});
```

### Typescript

Storybook handles most [Typescript](https://www.typescriptlang.org/) configurations, but this framework adds additional support for Next.js's support for [Absolute Imports and Module path aliases](https://nextjs.org/docs/pages/building-your-application/configuring/absolute-imports-and-module-aliases). In short, it takes into account your `tsconfig.json`'s [baseUrl](https://www.typescriptlang.org/tsconfig#baseUrl) and [paths](https://www.typescriptlang.org/tsconfig#paths). Thus, a `tsconfig.json` like the one below would work out of the box.

```json title="tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}
```

### React Server Components (RSC)

(⚠️ **Experimental**)

If your app uses [React Server Components (RSC)](https://nextjs.org/docs/app/building-your-application/rendering/server-components), Storybook can render them in stories in the browser.

To enable this set the `experimentalRSC` feature flag in your `.storybook/main.js|ts` config:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  features: {
    experimentalRSC: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  features: {
    experimentalRSC: true,
  },
});
```

Setting this flag automatically wraps your story in a [Suspense](https://react.dev/reference/react/Suspense) wrapper, which is able to render asynchronous components in NextJS's version of React.

If this wrapper causes problems in any of your existing stories, you can selectively disable it using the `react.rsc` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) at the global/component/story level:

```ts
// MyServerComponent.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const meta = {
  component: MyServerComponent,
  parameters: {
    react: { rsc: false },
  },
} satisfies Meta<typeof MyServerComponent>;
export default meta;
```

```ts
// MyServerComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: MyServerComponent,
  parameters: {
    react: { rsc: false },
  },
});
```

Note that wrapping your server components in Suspense does not help if your server components access server-side resources like the file system or Node-specific libraries. To work around this, you'll need to mock out your data access layer using [Webpack aliases](https://webpack.js.org/configuration/resolve/#resolvealias) or an addon like [storybook-addon-module-mock](https://storybook.js.org/addons/storybook-addon-module-mock).

If your server components access data via the network, we recommend using the [MSW Storybook Addon](https://storybook.js.org/addons/msw-storybook-addon) to mock network requests.

In the future we will provide better mocking support in Storybook and support for [Server Actions](https://nextjs.org/docs/app/api-reference/functions/server-actions).

## Notes for Yarn v2 and v3 users

If you're using [Yarn](https://yarnpkg.com/) v2 or v3, you may run into issues where Storybook can't resolve `style-loader` or `css-loader`. For example, you might get errors like:

```
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
```

This is because those versions of Yarn have different package resolution rules than Yarn v1.x. If this is the case for you, please install the package directly.

## FAQ

### How do I manually install the Next.js framework?

First, install the framework:

```shell
npm install --save-dev @storybook/nextjs
```

```shell
pnpm add --save-dev @storybook/nextjs
```

```shell
yarn add --dev @storybook/nextjs
```

Then, update your `.storybook/main.js|ts` to change the framework property:

```diff
// .storybook/main.ts — CSF 3
- import type { StorybookConfig } from '@storybook/your-previous-framework';
+ import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  // ...
-  framework: '@storybook/react-webpack5',
+  framework: '@storybook/nextjs',
};

export default config;
```

```diff
// .storybook/main.ts — CSF Next 🧪
- import { defineMain } from '@storybook/your-previous-framework/node';
+ import { defineMain } from '@storybook/nextjs/node';

export default defineMain({
  // ...
-  framework: '@storybook/react-webpack5',
+  framework: '@storybook/nextjs',
});
```

Finally, if you were using Storybook plugins to integrate with Next.js, those are no longer necessary when using this framework and can be removed:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  addons: [
    // ...
    // 👇 These can both be removed
    // 'storybook-addon-next',
    // 'storybook-addon-next-router',
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  addons: [
    // ...
    // 👇 These can both be removed
    // 'storybook-addon-next',
    // 'storybook-addon-next-router',
  ],
});
```

### How do I migrate to the Next.js Vite framework?

Please refer to the [migration instructions for `@storybook/nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md#how-do-i-migrate-from-the-nextjs-webpack-5-addon).

### Stories for pages/components which fetch data

Next.js pages can fetch data directly within server components in the `app` directory, which often include module imports that only run in a Node.js environment. This does not (currently) work within Storybook, because if you import from a Next.js page file containing those node module imports in your stories, your Storybook's Webpack will crash because those modules will not run in a browser. To get around this, you can extract the component in your page file into a separate file and import that pure component in your stories. Or, if that's not feasible for some reason, you can [polyfill those modules](https://webpack.js.org/configuration/node/) in your Storybook's [`webpackFinal` configuration](https://storybook.js.org/docs/builders/webpack.md#override-the-default-configuration).

**Before**

```jsx title="app/my-page/index.jsx"
async function getData() {
  const res = await fetch(...);
  // ...
}

// Using this component in your stories will break the Storybook build
export default async function Page() {
  const data = await getData();

  return // ...
}
```

**After**

```jsx title="app/my-page/index.jsx"
// Use this component in your stories

async function getData() {
  const res = await fetch(...);
  // ...
}

export default async function Page() {
  const data = await getData();

  return ;
}
```

### Statically imported images won't load

Make sure you are treating image imports the same way you treat them when using `next/image` in normal development.

Before using this framework, image imports would import the raw path to the image (e.g. `'static/media/stories/assets/logo.svg'`). Now image imports work the "Next.js way", meaning that you now get an object when importing an image. For example:

```jsonc
// Image import object
{
  "src": "static/media/stories/assets/logo.svg",
  "height": 48,
  "width": 48,
  "blurDataURL": "static/media/stories/assets/logo.svg",
}
```

Therefore, if something in Storybook isn't showing the image properly, make sure you expect the object to be returned from an import instead of only the asset path.

See [local images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#local-images) for more detail on how Next.js treats static image imports.

### Module not found: Error: Can't resolve `package name`

You might get this if you're using Yarn v2 or v3. See [Notes for Yarn v2 and v3 users](#notes-for-yarn-v2-and-v3-users) for more details.

### Should I use the Vite or Webpack version?

We recommend using [`@storybook/nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md) (Vite-based) for most projects because it offers faster builds, better test support, and a simpler configuration. However, if your project has custom Webpack configurations that are incompatible with Vite, use this framework instead.

### Error: You are importing avif images, but you don't have sharp installed. You have to install sharp in order to use image optimization features in Next.js.

`sharp` is a dependency of Next.js's image optimization feature. If you see this error, you need to install `sharp` in your project.

```bash
npm install sharp
```

```bash
yarn add sharp
```

```bash
pnpm add sharp
```

You can refer to the [Install `sharp` to Use Built-In Image Optimization](https://nextjs.org/docs/messages/install-sharp) in the Next.js documentation for more information.

## API

### Modules

The `@storybook/nextjs` package exports several modules that enable you to [mock](#mocking-modules) Next.js's internal behavior.

#### `@storybook/nextjs/export-mocks`

Type: `{ getPackageAliases: ({ useESM?: boolean }) => void }`

`getPackageAliases` is a helper for generating the aliases needed to set up [portable stories](#portable-stories).

```ts title="jest.config.ts"

// 👇 Import the utility function

const createJestConfig = nextJest({
  // Provide the path to your Next.js app to load next.config.js and .env files in your test environment
  dir: './',
});

const config: Config = {
  testEnvironment: 'jsdom',
  // ... rest of Jest config
  moduleNameMapper: {
    ...getPackageAliases(), // 👈 Add the utility as mapped module names
  },
};

export default createJestConfig(config);
```

#### `@storybook/nextjs/cache.mock`

Type: `typeof import('next/cache')`

This module exports mocked implementations of the `next/cache` module's exports. You can use it to create your own mock implementations or assert on mock calls in a story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

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

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

export const Submitted: Story = {
  async play({ canvas, userEvent }) {
    const submitButton = canvas.getByRole('button', { name: /submit/i });
    await userEvent.click(saveButton);
    // 👇 Use any mock assertions on the function
    await expect(revalidatePath).toHaveBeenCalledWith('/');
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
});

export const Submitted = meta.story({
  async play({ canvas, userEvent }) {
    const submitButton = canvas.getByRole('button', { name: /submit/i });
    await userEvent.click(saveButton);
    // 👇 Use any mock assertions on the function
    await expect(revalidatePath).toHaveBeenCalledWith('/');
  },
});
```

#### `@storybook/nextjs/headers.mock`

Type: [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies#cookiessetname-value-options), [`headers`](https://nextjs.org/docs/app/api-reference/functions/headers) and [`draftMode`](https://nextjs.org/docs/app/api-reference/functions/draft-mode) from Next.js

This module exports _writable_ mocked implementations of the `next/headers` module's exports. You can use it to set up cookies or headers that are read in your story, and to later assert that they have been called.

Next.js's default [`headers()`](https://nextjs.org/docs/app/api-reference/functions/headers) export is read-only, but this module exposes methods allowing you to write to the headers:

- **`headers().append(name: string, value: string)`**: Appends the value to the header if it exists already.
- **`headers().delete(name: string)`**: Deletes the header
- **`headers().set(name: string, value: string)`**: Sets the header to the value provided.

For cookies, you can use the existing API to write them. E.g., `cookies().set('firstName', 'Jane')`.

Because `headers()`, `cookies()` and their sub-functions are all mocks you can use any [mock utilities](https://vitest.dev/api/mock.html) in your stories, like `headers().getAll.mock.calls`.

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

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

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

export const LoggedInEurope: Story = {
  async beforeEach() {
    // 👇 Set mock cookies, headers and draft mode ahead of rendering
    cookies().set('username', 'Sol');
    headers().set('timezone', 'Central European Summer Time');
    draftMode.mockReturnValue({
      isEnabled: true,
      enable: fn(),
      disable: fn(),
    });
  },
  async play() {
    // 👇 Assert that your component called the mocks
    await expect(cookies().get).toHaveBeenCalledOnce();
    await expect(cookies().get).toHaveBeenCalledWith('username');
    await expect(headers().get).toHaveBeenCalledOnce();
    await expect(headers().get).toHaveBeenCalledWith('timezone');
    await expect(draftMode).toHaveBeenCalled();
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
});

export const LoggedInEurope = meta.story({
  async beforeEach() {
    // 👇 Set mock cookies, headers and draft mode ahead of rendering
    cookies().set('username', 'Sol');
    headers().set('timezone', 'Central European Summer Time');
    draftMode.mockReturnValue({
      isEnabled: true,
      enable: fn(),
      disable: fn(),
    });
  },
  async play() {
    // 👇 Assert that your component called the mocks
    await expect(cookies().get).toHaveBeenCalledOnce();
    await expect(cookies().get).toHaveBeenCalledWith('username');
    await expect(headers().get).toHaveBeenCalledOnce();
    await expect(headers().get).toHaveBeenCalledWith('timezone');
    await expect(draftMode).toHaveBeenCalled();
  },
});
```

#### `@storybook/nextjs/navigation.mock`

Type: `typeof import('next/navigation') & getRouter: () => ReturnType<typeof import('next/navigation')['useRouter']>`

This module exports mocked implementations of the `next/navigation` module's exports. It also exports a `getRouter` function that returns a mocked version of [Next.js's `router` object from `useRouter`](https://nextjs.org/docs/app/api-reference/functions/use-router#userouter), allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

const meta = {
  component: MyForm,
  parameters: {
    nextjs: {
      // 👇 As in the Next.js application, next/navigation only works using App Router
      appDirectory: true,
    },
  },
} satisfies Meta<typeof MyForm>;

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

export const Unauthenticated: Story = {
  async play() {
    // 👇 Assert that your component called redirect()
    await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
  },
};

export const GoBack: Story = {
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
  parameters: {
    nextjs: {
      // 👇 As in the Next.js application, next/navigation only works using App Router
      appDirectory: true,
    },
  },
});

export const Unauthenticated = meta.story({
  async play() {
    // 👇 Assert that your component called redirect()
    await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
  },
});

export const GoBack = meta.story({
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
});
```

#### `@storybook/nextjs/router.mock`

Type: `typeof import('next/router') & getRouter: () => ReturnType<typeof import('next/router')['useRouter']>`

This module exports mocked implementations of the `next/router` module's exports. It also exports a `getRouter` function that returns a mocked version of [Next.js's `router` object from `useRouter`](https://nextjs.org/docs/pages/api-reference/functions/use-router#router-object), allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

```ts
// MyForm.stories.ts — CSF 3
// Replace your-framework with nextjs or nextjs-vite

// 👇 Must include the `.mock` portion of filename to have mocks typed correctly

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

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

export const GoBack: Story = {
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
};
```

```ts
// MyForm.stories.ts — CSF Next 🧪

/*
 * Replace your-framework with nextjs or nextjs-vite
 * 👇 Must include the `.mock` portion of filename to have mocks typed correctly
 */

const meta = preview.meta({
  component: MyForm,
});

export const GoBack = meta.story({
  async play({ canvas, userEvent }) {
    const backBtn = await canvas.findByText('Go back');

    await userEvent.click(backBtn);
    // 👇 Assert that your component called back()
    await expect(getRouter().back).toHaveBeenCalled();
  },
});
```

### Options

You can pass an options object for additional configuration if needed:

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  framework: {
    name: '@storybook/your-framework',
    options: {
      nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  framework: {
    name: '@storybook/your-framework',
    options: {
      nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
    },
  },
});
```

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For Next.js, available options can be found in the [Webpack builder docs](https://storybook.js.org/docs/builders/webpack.md).

#### `nextConfigPath`

Type: `string`

The absolute path to the `next.config.js` file. This is necessary if you have a custom `next.config.js` file that is not in the root directory of your project.

### Parameters

This framework contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `nextjs` namespace:

#### `image`

Type: `object`

Props to pass to every instance of `next/image`. See [next/image docs](https://nextjs.org/docs/pages/api-reference/components/image) for more details.

#### `appDirectory`

Type: `boolean`

Default: `false`

If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true`. Because this is a parameter, you can apply it to a [single story](https://storybook.js.org/docs/api/parameters.md#story-parameters), [all stories for a component](https://storybook.js.org/docs/api/parameters.md#meta-parameters), or [every story in your Storybook](https://storybook.js.org/docs/api/parameters.md#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.

#### `navigation`

Type:

```ts
{
  asPath?: string;
  pathname?: string;
  query?: Record<string, string>;
  segments?: (string | [string, string])[];
}
```

Default value:

```js
{
  segments: [];
}
```

The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.

#### `router`

Type:

```ts
{
  asPath?: string;
  pathname?: string;
  query?: Record<string, string>;
}
```

The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
> Source: https://storybook.js.org/docs/get-started/frameworks/nextjs
---

# Storybook for Preact with Vite

Storybook for Preact & Vite is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [Preact](https://preactjs.com/) applications built with [Vite](https://vitejs.dev/).

## Install

To install Storybook in an existing Preact project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## FAQ

### How do I manually install the Preact framework?

First, install the framework:

Then, update your `.storybook/main.js|ts` to change the framework property:

## API

### Options

You can pass an options object for additional configuration if needed:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).
> Source: https://storybook.js.org/docs/get-started/frameworks/preact-vite
---

# Storybook for React with Vite

Storybook for React & Vite is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [React](https://react.dev/) applications built with [Vite](https://vitejs.dev/).

## Install

To install Storybook in an existing React project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## FAQ

### How do I migrate from the React Webpack framework?

The `upgrade` command should prompt you to migrate to `@storybook/react-vite` when you run it:

```shell
npx storybook@latest upgrade
```

```shell
pnpm dlx storybook@latest upgrade
```

```shell
yarn dlx storybook@latest upgrade
```

In case that auto-migration does not work for your project, refer to the manual installation instructions below.

### How do I manually install the React framework?

First, install the framework:

```shell
npm install --save-dev @storybook/react-vite
```

```shell
pnpm add --save-dev @storybook/react-vite
```

```shell
yarn add --dev @storybook/react-vite
```

Then, update your `.storybook/main.js|ts` to change the framework property:

```ts
// .storybook/main.ts — CSF 3

const config: StorybookConfig = {
  // ...
  // framework: '@storybook/react-webpack5', 👈 Remove this
  framework: '@storybook/react-vite', // 👈 Add this
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  // ...
  // framework: '@storybook/react-webpack5', 👈 Remove this
  framework: '@storybook/react-vite', // 👈 Add this
});
```

## API

### Options

You can pass an options object for additional configuration if needed:

```ts
// .storybook/main.ts — CSF 3

const config: StorybookConfig = {
  framework: {
    name: '@storybook/react-vite',
    options: {
      // ...
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: {
    name: '@storybook/react-vite',
    options: {
      // ...
    },
  },
});
```

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).
> Source: https://storybook.js.org/docs/get-started/frameworks/react-vite
---

# Storybook for React with Webpack

Storybook for React & Webpack is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [React](https://react.dev/) applications built with [Webpack](https://webpack.js.org/).

**We recommend using [`@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite.md)** for most React projects. The Vite-based framework is faster, more modern, and offers better support for testing features.

Use this Webpack-based framework (`@storybook/react-webpack5`) only if you need specific Webpack features not available in Vite.

## Install

To install Storybook in an existing React project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Configure

### Create React App (CRA)

Support for [Create React App](https://create-react-app.dev/) is handled by [`@storybook/preset-create-react-app`](https://github.com/storybookjs/presets/tree/master/packages/preset-create-react-app).

This preset enables support for all CRA features, including Sass/SCSS and TypeScript.

### Manually initialized apps

If you're working on an app that was initialized manually (i.e., without the use of CRA), ensure that your app has [react-dom](https://www.npmjs.com/package/react-dom) included as a dependency. Failing to do so can lead to unforeseen issues with Storybook and your project.

## FAQ

### How do I manually install the React Webpack framework?

First, install the framework:

```shell
npm install --save-dev @storybook/react-webpack5
```

```shell
pnpm add --save-dev @storybook/react-webpack5
```

```shell
yarn add --dev @storybook/react-webpack5
```

Next, install and register your appropriate compiler addon, depending on whether you're using SWC (recommended) or Babel:

If your project is using [Create React App](#create-react-app-cra), you can skip this step.

```sh
npx storybook@latest add @storybook/addon-webpack5-compiler-swc
```

```sh
pnpm dlx storybook@latest add @storybook/addon-webpack5-compiler-swc
```

```sh
yarn dlx storybook@latest add @storybook/addon-webpack5-compiler-swc
```

or

```sh
npx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

```sh
pnpm dlx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

```sh
yarn dlx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

More details can be found in the [Webpack builder docs](https://storybook.js.org/docs/builders/webpack.md#compiler-support).

Finally, update your `.storybook/main.js|ts` to change the framework property:

```ts
// .storybook/main.ts — CSF 3

const config: StorybookConfig = {
  // ...
  framework: '@storybook/react-webpack5', // 👈 Add this
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  // ...
  framework: '@storybook/react-webpack5', // 👈 Add this
});
```

### How do I migrate to the React Vite framework?

Please refer to the [migration instructions for `@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite.md#how-do-i-migrate-from-the-react-webpack-framework).

## API

### Options

You can pass an options object for additional configuration if needed:

```ts
// .storybook/main.ts — CSF 3

const config: StorybookConfig = {
  framework: {
    name: '@storybook/react-webpack5',
    options: {
      // ...
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: {
    name: '@storybook/react-webpack5',
    options: {
      // ...
    },
  },
});
```

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Webpack builder docs](https://storybook.js.org/docs/builders/webpack.md).
> Source: https://storybook.js.org/docs/get-started/frameworks/react-webpack5
---

# Storybook for React Native Web

Storybook for React Native Web is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [React Native](https://reactnative.dev/). It uses [Vite](https://vitejs.dev/) to build your components for web browsers.

In addition to React Native Web, Storybook supports on-device [React Native](https://github.com/storybookjs/react-native) development. If you're unsure what's right for you, read our [comparison](#react-native-vs-react-native-web).

## Install

To install Storybook in an existing React Native project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## React Native vs React Native Web

If you’re building React Native (RN) components, Storybook has two options: Native and Web.

Both options provide a catalog of your stories that hot refreshes as you edit the code in your favorite editor. However, their implementations are quite different:

- **Native** - Runs inside your React Native application. It’s high-fidelity but has a limited feature set.
- **Web** - Displays your React Native components in the browser. It’s based on Storybook for Web, which is feature-rich and mature.

### Comparison

So, which option is right for you?

**Native.** You should choose this option if you want:

- **Native features** - Your components rely on device-specific features like native modules. It runs in your actual application, in-simulator, or on-device and provides full fidelity. The web version uses `react-native-web`, which works for most components but has [limitations](https://necolas.github.io/react-native-web/docs/react-native-compatibility/).
- **Mobile publication** - You want to share your Storybook on-device as part of a test build or embedded inside your application.

**Web.** You should choose this option if you want:

- [**Sharing**](https://storybook.js.org/docs/sharing/publish-storybook.md) - Publish to the web and share with your team or publicly.
- [**Documentation**](https://storybook.js.org/docs/writing-docs.md) - Auto-generated component docs or rich markdown docs in MDX.
- [**Testing**](https://storybook.js.org/docs/writing-tests.md) - Component, visual, and a11y tests for your components.
- [**Addons**](https://storybook.js.org/addons) - 500+ addons that improve development, documentation, testing, and integration with other tools.

**Both.** It’s also possible to use both options together. This increases Storybook’s install footprint but is a good option if you want native fidelity in addition to all of the web features. Learn more below.

### Using both React Native and React Native Web

The easiest way to use React Native and React Native Web is to select the **"Both"** option when installing Storybook. This will install and create configurations for both environments, allowing you to run Storybook for both in the same project.

When you select "Both", the installation will:

1. Install and configure React Native Storybook (on-device)
2. Install and configure React Native Web Storybook (web-based)
3. Set up both configurations in your project

After installation, you'll see instructions for both environments:

- React Native Storybook will require additional manual configuration steps (replacing app entry, wrapping metro config)
- React Native Web Storybook can be started immediately using the `storybook` command

However, you can install them separately if one version is installed. You can add a React Native Web Storybook alongside an existing React Native Storybook by running the install command and selecting "React Native Web" in the setup wizard, and vice versa.

## FAQ

### How do I migrate from the React Native Web addon?

The [React Native Web addon](https://github.com/storybookjs/addon-react-native-web) was a Webpack-based precursor to the React Native Web Vite framework (i.e., `@storybook/react-native-web-vite`). If you're using the addon, you should migrate to the framework, which is faster, more stable, maintained, and better documented. To do so, follow the steps below.

Run the following command to upgrade Storybook to the latest version:

```shell
npx storybook@latest upgrade
```

```shell
pnpm dlx storybook@latest upgrade
```

```shell
yarn dlx storybook@latest upgrade
```

This framework is designed to work with Storybook 8.5 and above for the best experience. We won't be able to provide support if you're using an older Storybook version.

Install the framework and its peer dependencies:

```shell
npm install --save-dev @storybook/react-native-web-vite vite
```

```shell
pnpm add --save-dev @storybook/react-native-web-vite vite
```

```shell
yarn add --dev @storybook/react-native-web-vite vite
```

Update your `.storybook/main.js|ts` to change the framework property and remove the `@storybook/addon-react-native-web` addon:

```ts
// .storybook/main.ts

const config: StorybookConfig = {
  addons: [
    '@storybook/addon-react-native-web', // 👈 Remove the addon
  ],
  // Replace @storybook/react-webpack5 with the Vite framework
  framework: '@storybook/react-native-web-vite',
};

export default config;
```

Finally, remove the addon and similar packages (i.e., `@storybook/react-webpack5` and `@storybook/addon-react-native-web`) from your project.

## API

### Options

You can pass an options object for additional configuration if needed:

```ts title=".storybook/main.ts"

const config: StorybookConfig = {
  framework: {
    name: '@storybook/react-native-web-vite',
    options: {
      modulesToTranspile: ['my-library'], // add libraries that are not transpiled for web by default

      // You should apply babel plugins and presets here for your project that you want to apply to your code
      // for example put the reanimated preset here if you are using reanimated
      // or the nativewind jsxImportSource for example
      pluginReactOptions: {
        jsxRuntime: 'automatic' | 'classic', // default: 'automatic'
        jsxImportSource: string, // default: 'react'
        babel:{
          plugins: Array<string | [string, any]>,
          presets: Array<string | [string, any]>,
          // ... other compatible babel options
        }
        include: Array<string|RegExp>,
        exclude: Array<string|RegExp>,
        // ... other compatible @vitejs/plugin-react options
      }
    },
  },
};

export default config;
```

#### Example configuration for reanimated

```ts title=".storybook/main.ts"
const config: StorybookConfig = {
  // ... rest of config

  framework: {
    name: '@storybook/react-native-web-vite',
    options: {
      pluginReactOptions: {
        babel: {
          plugins: [
            '@babel/plugin-proposal-export-namespace-from',
            'react-native-reanimated/plugin',
          ],
        },
      },
    },
  },

  // ... rest of config
};
```

#### Example configuration for nativewind

```ts title=".storybook/main.ts"
const config: StorybookConfig = {
  // ... rest of config

  framework: {
    name: '@storybook/react-native-web-vite',
    options: {
      pluginReactOptions: {
        jsxImportSource: 'nativewind',
      },
    },
  },
};
```

#### Example configuration to transpile additional node_modules

Let's say you need to transpile a library called `my-library` that is not transpiled for web by default.
You can add it to the `modulesToTranspile` option.

```ts title=".storybook/main.ts"
const config: StorybookConfig = {
  // ... rest of config

  framework: {
    name: '@storybook/react-native-web-vite',
    options: {
      modulesToTranspile: ['my-library'],
    },
  },
};
```

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).
> Source: https://storybook.js.org/docs/get-started/frameworks/react-native-web-vite
---

# Storybook for SvelteKit

Storybook for SvelteKit is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [SvelteKit](https://kit.svelte.dev/) applications.

## Install

To install Storybook in an existing SvelteKit project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Configure

This section covers SvelteKit support and configuration options.

### Supported features

All Svelte language features are supported out of the box, as the Storybook framework uses the Svelte compiler directly.
However, SvelteKit has some [Kit-specific modules](https://kit.svelte.dev/docs/modules) that aren't supported. Here's a breakdown of what will and will not work within Storybook:

| Module                                                                     | Status                 | Note                                                                                                                                    |
| -------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [`$app/environment`](https://svelte.dev/docs/kit/$app-environment)         | ✅ Supported           | `version` is always empty in Storybook.                                                                                                 |
| [`$app/forms`](https://svelte.dev/docs/kit/$app-forms)                     | ⚠️ **Experimental**    | See [How to mock](#how-to-mock).                                                                                                        |
| [`$app/navigation`](https://svelte.dev/docs/kit/$app-navigation)           | ⚠️ **Experimental**    | See [How to mock](#how-to-mock).                                                                                                        |
| [`$app/paths`](https://svelte.dev/docs/kit/$app-paths)                     | ✅ Supported           | Requires SvelteKit 1.4.0 or newer.                                                                                                      |
| [`$app/state`](https://svelte.dev/docs/kit/$app-state)                     | ⚠️ **Experimental**    | Requires SvelteKit `v2.12` or newer. See [How to mock](#how-to-mock).                                                                   |
| [`$app/stores`](https://svelte.dev/docs/kit/$app-stores)                   | ⚠️ **Experimental**    | See [How to mock](#how-to-mock).                                                                                                        |
| [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public)   | 🚧 Partially supported | Only supported in development mode. Storybook is built as a static app with no server-side API, so it cannot dynamically serve content. |
| [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public)     | ✅ Supported           |                                                                                                                                         |
| [`$lib`](https://svelte.dev/docs/kit/$lib)                                 | ✅ Supported           |                                                                                                                                         |
| [`@sveltejs/kit/*`](https://svelte.dev/docs/kit/@sveltejs-kit)             | ✅ Supported           |                                                                                                                                         |
| [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private) | ⛔ Not supported       | This is a server-side feature, and Storybook renders all components on the client.                                                      |
| [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private)   | ⛔ Not supported       | This is a server-side feature, and Storybook renders all components on the client.                                                      |
| [`$service-worker`](https://svelte.dev/docs/kit/$service-worker)           | ⛔ Not supported       | This is a service worker feature, which does not apply to Storybook.                                                                    |

### How to mock

To mock a SvelteKit import you can define it within `parameters.sveltekit_experimental`:

The [available parameters](#parameters) are documented in the API section, below.

#### Mocking links

The default link-handling behavior (e.g., when clicking an `<a href="..." />` element) is to log an action to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

You can override this by assigning an object to `parameters.sveltekit_experimental.hrefs`, where the keys are strings representing an href, and the values define your mock. For example:

See the [API reference](#hrefs) for more information.

## Writing native Svelte stories

Storybook provides a Svelte [addon](https://storybook.js.org/addons/@storybook/addon-svelte-csf) maintained by the community, enabling you to write stories for your Svelte components using the template syntax.

The community actively maintains the Svelte CSF addon but still lacks some features currently available in the official Storybook Svelte framework support. For more information, see the [addon's documentation](https://github.com/storybookjs/addon-svelte-csf).

### Setup

If you initialized your project with the Sveltekit framework, the addon has already been installed and configured for you. However, if you're [migrating](#automatic-migration) from a previous version, you'll need to take additional steps to enable this feature.

Run the following command to install the addon.

The CLI's [`add`](https://storybook.js.org/docs/api/cli-options.md#add) command automates the addon's installation and setup. To install it manually, see our [documentation](https://storybook.js.org/docs/addons/install-addons.md#manual-installation) on how to install addons.

Update your Storybook configuration file (i.e., `.storybook/main.js|ts`) to enable support for this format.

### Configure

By default, the Svelte [addon](https://storybook.js.org/addons/@storybook/addon-svelte-csf) addon offers zero-config support for Storybook's SvelteKit framework. However, you can extend your Storybook configuration file (i.e., `.storybook/main.js|ts`) and provide additional addon options. Listed below are the available options and examples of how to use them.

| Options          | Description                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `legacyTemplate` | Enables support for the `Template` component for backward compatibility. <br/> `options: { legacyTemplate: true }` |

Enabling the `legacyTemplate` option can introduce a performance overhead and should be used cautiously. For more information, refer to the [addon's documentation](https://github.com/storybookjs/addon-svelte-csf/blob/next/README.md#legacy-api).

### Upgrade to Svelte CSF addon v5

With the Svelte 5 release, Storybook's Svelte CSF addon has been updated to support the new features. This guide will help you migrate to the latest version of the addon. Below is an overview of the major changes in version 5.0 and the steps needed to upgrade your project.

#### Simplified story API

If you are using the `Meta` component or the `meta` named export to define the story's metadata (e.g., [parameters](https://storybook.js.org/docs/writing-stories/parameters.md)), you'll need to update your stories to use the new `defineMeta` function. This function returns an object with the required information, including a `Story` component that you must use to define your component stories.

#### Story templates

If you used the `Template` component to control how the component renders in the Storybook, this feature was replaced with built-in children support in the `Story` component, enabling you to compose components and define the UI structure directly in the story.

If you need support for the `Template` component, the addon provides a feature flag for backward compatibility. For more information, see the [configuration options](#configure).

#### Story slots to snippets

With Svelte's slot deprecation and the introduction of reusable [`snippets`](https://svelte.dev/docs/svelte/v5-migration-guide#Snippets-instead-of-slots), the addon also introduced support for this feature allowing you to extend the `Story` component and provide a custom snippet to provide dynamic content to your stories. `Story` accepts a `template` snippet, allowing you to create dynamic stories without losing reactivity.

```svelte title="MyComponent.stories.svelte"
<script>
  import { defineMeta } from '@storybook/addon-svelte-csf';

  import MyComponent from './MyComponent.svelte';

  const { Story } = defineMeta({
    component: MyComponent,
  });
</script>

  {#snippet template(args)}
    Reactive component
  {/snippet}

```

#### Tags support

If you enabled automatic documentation generation with the `autodocs` story property, you must replace it with [`tags`](https://storybook.js.org/docs/writing-stories/tags.md). This property allows you to categorize and filter stories based on specific criteria and generate documentation based on the tags applied to the stories.

## FAQ

### How do I manually install the SvelteKit framework?

First, install the framework:

Then, update your `.storybook/main.js|ts` to change the framework property:

Finally, these packages are now either obsolete or part of `@storybook/sveltekit`, so you no longer need to depend on them directly. You can remove them (`npm uninstall`, `yarn remove`, `pnpm remove`) from your project:

- `@storybook/svelte-vite`
- `storybook-builder-vite`
- `@storybook/builder-vite`

## API

### Parameters

This framework contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `sveltekit_experimental` namespace:

#### `forms`

Type: `{ enhance: () => void }`

Provides mocks for the [`$app/forms`](https://svelte.dev/docs/kit/$app-forms) module.

##### `forms.enhance`

Type: `() => void`

A callback that will be called when a form with [`use:enhance`](https://kit.svelte.dev/docs/form-actions#progressive-enhancement-use-enhance) is submitted.

#### `hrefs`

Type: `Record<[path: string], (to: string, event: MouseEvent) => void | { callback: (to: string, event: MouseEvent) => void, asRegex?: boolean }>`

If you have an `<a />` tag inside your code with the `href` attribute that matches one or more of the links defined (treated as regex based if the `asRegex` property is `true`) the corresponding `callback` will be called. If no matching `hrefs` are defined, an action will be logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md). See [Mocking links](#mocking-links) for an example.

#### `navigation`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation)

Provides mocks for the [`$app/navigation`](https://svelte.dev/docs/kit/$app-navigation) module.

##### `navigation.goto`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#goto)

A callback that will be called whenever [`goto`](https://svelte.dev/docs/kit/$app-navigation#goto) is called. If no function is provided, an action will be logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

##### `navigation.pushState`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#pushState)

A callback that will be called whenever [`pushState`](https://svelte.dev/docs/kit/$app-navigation#pushState) is called. If no function is provided, an action will be logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

##### `navigation.replaceState`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#replaceState)

A callback that will be called whenever [`replaceState`](https://svelte.dev/docs/kit/$app-navigation#replaceState) is called. If no function is provided, an action will be logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

##### `navigation.invalidate`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#invalidate)

A callback that will be called whenever [`invalidate`](https://svelte.dev/docs/kit/$app-navigation#invalidate) is called. If no function is provided, an action will be logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

##### `navigation.invalidateAll`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#invalidateAll)

A callback that will be called whenever [`invalidateAll`](https://svelte.dev/docs/kit/$app-navigation#invalidateAll) is called. If no function is provided, an action will be logged to the [Actions panel](https://storybook.js.org/docs/essentials/actions.md).

##### `navigation.afterNavigate`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#afterNavigate)

An object that will be passed to the [`afterNavigate`](https://svelte.dev/docs/kit/$app-navigation#afterNavigate) function, which will be invoked when the `onMount` event fires.

#### `stores`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-stores)

Provides mocks for the [`$app/stores`](https://svelte.dev/docs/kit/$app-stores) module.

##### `stores.navigating`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-stores#navigating)

A partial version of the [`navigating`](https://svelte.dev/docs/kit/$app-stores#navigating) store.

##### `stores.page`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-stores#page)

A partial version of the [`page`](https://svelte.dev/docs/kit/$app-stores#page) store.

##### `stores.updated`

Type: boolean

A boolean representing the value of [`updated`](https://svelte.dev/docs/kit/$app-stores#updated) (you can also access `updated.check()` which will be a no-op).

#### `state`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-state)

Provides mocks for the [`$app/state`](https://svelte.dev/docs/kit/$app-state) module.

##### `state.navigating`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-state#navigating)

A partial version of the [`navigating`](https://svelte.dev/docs/kit/$app-state#navigating) store.

##### `state.page`

Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-state#page)

A partial version of the [`page`](https://svelte.dev/docs/kit/$app-state#page) store.

##### `state.updated`

Type: `{ current: boolean }`

An object representing the current value of [`updated`](https://svelte.dev/docs/kit/$app-state#updated). You can also access `updated.check()`, which will be a no-op.

### Options

You can pass an options object for additional configuration if needed:

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For Sveltekit, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).

#### `docgen`

Type: `boolean`

Default: `true`

Enables or disables automatic documentation generation for component properties. When disabled, Storybook will skip the docgen processing step during build, which can improve build performance.

#### When to disable docgen

Disabling docgen can improve build performance for large projects, but [argTypes won't be inferred automatically](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference), which will prevent features like [Controls](https://storybook.js.org/docs/essentials/controls.md) and [docs](https://storybook.js.org/docs/writing-docs/autodocs.md) from working as expected. To use those features, you will need to [define `argTypes` manually](https://storybook.js.org/docs/api/arg-types.md#manually-specifying-argtypes).
> Source: https://storybook.js.org/docs/get-started/frameworks/sveltekit
---

# Storybook for Svelte with Vite

Storybook for Svelte & Vite is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for applications using [Svelte](https://svelte.dev/) built with [Vite](https://vitejs.dev/).

## Install

To install Storybook in an existing Svelte project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Writing native Svelte stories

Storybook provides a Svelte [addon](https://storybook.js.org/addons/@storybook/addon-svelte-csf) maintained by the community, enabling you to write stories for your Svelte components using the template syntax.

The community actively maintains the Svelte CSF addon but still lacks some features currently available in the official Storybook Svelte framework support. For more information, see the [addon's documentation](https://github.com/storybookjs/addon-svelte-csf).

### Setup

If you initialized your project with the Svelte framework, the addon has already been installed and configured for you. However, if you're [migrating](#automatic-migration) from a previous version, you'll need to take additional steps to enable this feature.

Run the following command to install the addon.

The CLI's [`add`](https://storybook.js.org/docs/api/cli-options.md#add) command automates the addon's installation and setup. To install it manually, see our [documentation](https://storybook.js.org/docs/addons/install-addons.md#manual-installation) on how to install addons.

Update your Storybook configuration file (i.e., `.storybook/main.js|ts`) to enable support for this format.

### Configure

By default, the Svelte [addon](https://storybook.js.org/addons/@storybook/addon-svelte-csf) offers zero-config support for Storybook's Svelte framework. However, you can extend your Storybook configuration file (i.e., `.storybook/main.js|ts`) and provide additional addon options. Listed below are the available options and examples of how to use them.

| Options          | Description                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `legacyTemplate` | Enables support for the `Template` component for backward compatibility. <br/> `options: { legacyTemplate: true }` |

Enabling the `legacyTemplate` option can introduce a performance overhead and should be used cautiously. For more information, refer to the [addon's documentation](https://github.com/storybookjs/addon-svelte-csf/blob/next/README.md#legacy-api).

### Upgrade to Svelte CSF addon v5

With the Svelte 5 release, Storybook's Svelte CSF addon has been updated to support the new features. This guide will help you migrate to the latest version of the addon. Below is an overview of the major changes in version 5.0 and the steps needed to upgrade your project.

#### Simplified story API

If you are using the `Meta` component or the `meta` named export to define the story's metadata (e.g., [parameters](https://storybook.js.org/docs/writing-stories/parameters.md)), you'll need to update your stories to use the new `defineMeta` function. This function returns an object with the required information, including a `Story` component that you must use to define your component stories.

#### Story templates

If you used the `Template` component to control how the component renders in the Storybook, this feature was replaced with built-in children support in the `Story` component, enabling you to compose components and define the UI structure directly in the story.

If you need support for the `Template` component, the addon provides a feature flag for backward compatibility. For more information, see the [configuration options](#configure).

#### Story slots to snippets

With Svelte's slot deprecation and the introduction of reusable [`snippets`](https://svelte.dev/docs/svelte/v5-migration-guide#Snippets-instead-of-slots), the addon also introduced support for this feature allowing you to extend the `Story` component and provide a custom snippet to provide dynamic content to your stories. `Story` accepts a `template` snippet, allowing you to create dynamic stories without losing reactivity.

```svelte title="MyComponent.stories.svelte"
<script>
  import { defineMeta } from '@storybook/addon-svelte-csf';

  import MyComponent from './MyComponent.svelte';

  const { Story } = defineMeta({
    component: MyComponent,
  });
</script>

  {#snippet template(args)}
    Reactive component
  {/snippet}

```

#### Tags support

If you enabled automatic documentation generation with the `autodocs` story property, you must replace it with [`tags`](https://storybook.js.org/docs/writing-stories/tags.md). This property allows you to categorize and filter stories based on specific criteria and generate documentation based on the tags applied to the stories.

## FAQ

### How do I manually install the Svelte framework?

First, install the framework:

Then, update your `.storybook/main.js|ts` to change the framework property:

## API

### Options

You can pass an options object for additional configuration if needed:

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).

#### `docgen`

Type: `boolean`

Default: `true`

Enables or disables automatic documentation generation for component properties. When disabled, Storybook will skip the docgen processing step during build, which can improve build performance.

#### When to disable docgen

Disabling docgen can improve build performance for large projects, but [argTypes won't be inferred automatically](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference), which will prevent features like [Controls](https://storybook.js.org/docs/essentials/controls.md) and [docs](https://storybook.js.org/docs/writing-docs/autodocs.md) from working as expected. To use those features, you will need to [define `argTypes` manually](https://storybook.js.org/docs/api/arg-types.md#manually-specifying-argtypes).
> Source: https://storybook.js.org/docs/get-started/frameworks/svelte-vite
---

# Storybook for TanStack React

Storybook for TanStack React is Storybook's [framework](https://storybook.js.org/docs/contribute/framework.md) integration for [TanStack Router](https://tanstack.com/router) and [TanStack Start](https://tanstack.com/start/latest) applications built with [React](https://react.dev/) and [Vite](https://vitejs.dev/).

It builds on [`@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite.md) to add router-aware story rendering, automatic router mocking, and mocked TanStack Start server functions. Components that depend on routing or server functions can render inside Storybook without booting your full app runtime.

## Install

To install Storybook in an existing TanStack Router or TanStack Start project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md), and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

This integration expects a TanStack Router application with `@tanstack/react-router` available in your project. If your app uses TanStack Start APIs such as server functions, keep the matching TanStack Start packages installed as well.

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Configure

Storybook for TanStack React uses Vite through [`@storybook/builder-vite`](https://storybook.js.org/docs/builders/vite.md) and automatically wraps each story in a [memory-backed TanStack Router](https://tanstack.com/router/latest/docs/guide/history-types#memory-routing). This gives you a working router context in Storybook without having to boot your full application shell.

Out of the box, it supports these workflows:

- Supply a TanStack Route to render it as the story component
- Set the initial route, params, and query string per story
- Override `loader`, `beforeLoad`, and more on the story route without modifying the original route object via `routeOverrides`
- Automatically mock `@tanstack/react-router` so navigation hooks work in stories and navigation attempts can be observed
- Automatically stub TanStack Start server and runtime entry points so components using server functions can render in Storybook

### Routing

#### Rendering a Route

Supply a TanStack Route object via `parameters.tanstack.router.route`. Storybook extracts the route's React component from the route and keeps the route available for typed router configuration.

```ts
// Page.stories.ts — CSF 3

const meta = {
  parameters: {
    layout: 'fullscreen',
    tanstack: {
      router: {
        route: Route, // 👈 Supply the Route here
        // 👇 Rest of these properties are type-safe
        params: { id: '42' },
        query: { tab: 'details' },
      },
    },
  },
} satisfies Meta<typeof Route>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Default: Story = {};

export const WithCustomLoader: Story = {
  parameters: {
    tanstack: {
      router: {
        route: Route, // 👈 Supply the Route here
        // 👇 Rest of these properties are type-safe
        params: { id: '42' },
        routeOverrides: {
          '/items/$id': {
            loader: async () => ({
              item: { id: '42', name: 'Loaded inside Storybook' },
            }),
          },
        },
      },
    },
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  parameters: {
    layout: 'fullscreen',
    tanstack: {
      router: {
        route: Route, // 👈 Supply the Route here
        // 👇 Rest of these properties are type-safe
        params: { id: '42' },
        query: { tab: 'details' },
      },
    },
  },
});

export const Default = meta.story();

export const WithCustomLoader = meta.story({
  parameters: {
    tanstack: {
      router: {
        route: Route, // 👈 Supply the Route here
        // 👇 Rest of these properties are type-safe
        params: { id: '42' },
        routeOverrides: {
          '/items/$id': {
            loader: async () => ({
              item: { id: '42', name: 'Loaded inside Storybook' },
            }),
          },
        },
      },
    },
  },
});
```

##### Handling dynamic params (e.g., `/$id`)

Supply `params` alongside `routeOverrides` under `parameters.tanstack.router`. The `params` object is interpolated into the URL, and `routeOverrides` lets you stub the loader without touching the original route.

```ts
// Showcase.stories.ts — CSF 3

const meta = {
  parameters: {
    tanstack: {
      router: {
        route: Route,
        params: { id: '42' },
        routeOverrides: {
          '/showcase/$id': {
            loader: () => ({ item: mockItem }),
          },
        },
      },
    },
  },
} satisfies Meta<typeof Route>;

export default meta;
```

```ts
// Showcase.stories.ts — CSF Next 🧪

const meta = preview.meta({
  parameters: {
    tanstack: {
      router: {
        route: Route,
        params: { id: '42' },
        routeOverrides: {
          '/showcase/$id': {
            loader: () => ({ item: mockItem }),
          },
        },
      },
    },
  },
});
```

For the full set of properties, see [`Parameters`](#parameters).

#### Rendering nested routes

When `route` is a file route connected to your app's route tree, Storybook automatically includes parent layout routes so the story renders inside the same nested hierarchy as the real app. You can also pass the `routeTree` export from `routeTree.gen.ts` directly.

Use `path` to navigate to the specific route, and `routeOverrides` to stub guards or loaders on ancestor routes so the story can render independently.

```ts
// SettingsProfile.stories.ts — CSF 3

// 👇 Route file is part of the app route tree

const meta = {
  parameters: {
    tanstack: {
      router: {
        // 👇 Storybook walks up the tree to root and duplicates the full route tree,
        //    so parent layouts (e.g. the authenticated shell) also render.
        route: Route,
        path: '/settings/profile',
        // 👇 Stub out any parent route guards so the story can render standalone.
        routeOverrides: {
          '/_authenticated': { beforeLoad: () => {} },
        },
      },
    },
  },
} satisfies Meta<typeof Route>;

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

export const Default: Story = {};
```

```ts
// SettingsProfile.stories.ts — CSF Next 🧪

// 👇 Route file is part of the app route tree

const meta = preview.meta({
  parameters: {
    tanstack: {
      router: {
        // 👇 Storybook walks up the tree to root and duplicates the full route tree,
        //    so parent layouts (e.g. the authenticated shell) also render.
        route: Route,
        path: '/settings/profile',
        // 👇 Stub out any parent route guards so the story can render standalone.
        routeOverrides: {
          '/_authenticated': { beforeLoad: () => {} },
        },
      },
    },
  },
});

export const Default = meta.story();
```

#### Using router parameters with a non-Route component

If your story renders a regular React component instead of a route object, you can still provide routing context through `parameters.tanstack.router`.

```ts
// Page.stories.ts — CSF 3

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

export default meta;

type Story = StoryObj<typeof meta>;

export const Default: Story = {
  parameters: {
    tanstack: {
      router: {
        route: {
          path: '/demo/form/address',
        },
        query: { view: 'list' },
      },
    },
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Page,
});

export const Default = meta.story({
  parameters: {
    tanstack: {
      router: {
        route: {
          path: '/demo/form/address',
        },
        query: { view: 'list' },
      },
    },
  },
});
```

This is useful when your component reads from hooks such as `useRouterState`, `useSearch`, `useParams`, or `useLoaderData`, but you do not want to make the route itself the story component.

#### Defining search params and URL fragments (hashes)

Use `query` for search params (e.g., `?tab=details&page=2`) and `path` for a URL fragment (e.g., `#section-name`) under `parameters.tanstack.router`:

```ts
// Page.stories.ts — CSF 3

const meta = {
  parameters: {
    tanstack: {
      router: {
        route: Route,
      },
    },
  },
} satisfies Meta<typeof Route>;

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

export const WithHash: Story = {
  parameters: {
    tanstack: {
      // 👇 Provide the URL fragment (hash) for the route
      router: { path: '/#section-name' },
    },
  },
};

export const WithSearch: Story = {
  parameters: {
    tanstack: {
      // 👇 Provide the query string for the route
      router: { query: { tab: 'details', page: '2' } },
    },
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  parameters: {
    tanstack: {
      router: {
        route: Route,
      },
    },
  },
});

export const WithHash = meta.story({
  parameters: {
    tanstack: {
      // 👇 Provide the URL fragment (hash) for the route
      router: { path: '/#section-name' },
    },
  },
});

export const WithSearch = meta.story({
  parameters: {
    tanstack: {
      // 👇 Provide the query string for the route
      router: { query: { tab: 'details', page: '2' } },
    },
  },
});
```

#### Overriding route options per story

When a route has a [`loader`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#loader-method) or [`beforeLoad`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#beforeload-method) that calls real APIs, you can override those options per story without modifying the original route object. Pass `routeOverrides` under `parameters.tanstack.router`. Each key is a route ID and the value can override [`loader`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#loader-method), [`beforeLoad`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#beforeload-method), [`validateSearch`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#validatesearch-method), [`loaderDeps`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#loaderdeps-method), and [`context`](https://tanstack.com/router/latest/docs/guide/router-context).

Use `'__root__'` as the key to target the root route.

```ts
// UserCard.stories.ts — CSF 3

const meta = {
  title: 'Users/UserCard',
  parameters: {
    tanstack: {
      router: {
        route: Route,
        params: { userId: '42' },
        // 👇 Override the route's loader so the story doesn't call the real API.
        routeOverrides: {
          '/users/$userId': {
            loader: async () => ({ user: { id: '42', name: 'Ada Lovelace' } }),
          },
        },
      },
    },
  },
} satisfies Meta<typeof Route>;

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

export const Default: Story = {};
```

```ts
// UserCard.stories.ts — CSF Next 🧪

const meta = preview.meta({
  title: 'Users/UserCard',
  parameters: {
    tanstack: {
      router: {
        route: Route,
        params: { userId: '42' },
        // 👇 Override the route's loader so the story doesn't call the real API.
        routeOverrides: {
          '/users/$userId': {
            loader: async () => ({ user: { id: '42', name: 'Ada Lovelace' } }),
          },
        },
      },
    },
  },
});

export const Default = meta.story();
```

### Mocking

#### Automatic TanStack Router and TanStack Start mocks

This framework automatically redirects `@tanstack/react-router` imports to a Storybook-compatible mock layer. That mock re-exports TanStack Router APIs, keeps hooks such as [`useNavigate()`](https://tanstack.com/router/latest/docs/api/router/useNavigateHook), [`useSearch()`](https://tanstack.com/router/latest/docs/api/router/useSearchHook), and [`useParams()`](https://tanstack.com/router/latest/docs/api/router/useParamsHook) available in stories, and wires navigation attempts into Storybook spies.

For TanStack Start apps, the integration also stubs TanStack Start server and runtime entry points. This is what allows components that depend on server functions or Start-specific runtime modules to render in Storybook without a running Start server.

In practice, this means you can usually render TanStack Start components directly, and `createServerFn()` handlers are replaced with mock functions that you can observe and override in stories and tests.

#### Mocking server functions in stories

If your component imports a TanStack Start server function, Storybook turns that [`createServerFn().handler(...)`](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions) result into a mock function. That means you can override it per story with standard mock APIs.

For example, imagine your application code exports a server function like this:

```ts
// src/lib/updateProfile.ts

export const updateProfile = createServerFn({ method: 'POST' }).handler(
  async ({ data }: { data: { name: string } }) => {
    return { ok: true, name: data.name };
  },
);
```

In Storybook, you can override that function for each story:

```ts
// ProfileForm.stories.ts — CSF 3

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

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

export const Success: Story = {
  beforeEach: async () => {
    mocked(updateProfile).mockResolvedValue({ ok: true, name: 'Ada Lovelace' });
  },
  play: async ({ canvas, userEvent }) => {
    await userEvent.type(canvas.getByLabelText('Name'), 'Ada Lovelace');
    await userEvent.click(canvas.getByRole('button', { name: 'Save profile' }));

    await expect(updateProfile).toHaveBeenCalled();
  },
};

export const Failure: Story = {
  beforeEach: async () => {
    mocked(updateProfile).mockRejectedValue(new Error('Could not save profile'));
  },
};
```

```ts
// ProfileForm.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: ProfileForm,
});

export const Success = meta.story({
  beforeEach: async () => {
    mocked(updateProfile).mockResolvedValue({ ok: true, name: 'Ada Lovelace' });
  },
  play: async ({ canvas, userEvent }) => {
    await userEvent.type(canvas.getByLabelText('Name'), 'Ada Lovelace');
    await userEvent.click(canvas.getByRole('button', { name: 'Save profile' }));

    await expect(updateProfile).toHaveBeenCalled();
  },
});

export const Failure = meta.story({
  beforeEach: async () => {
    mocked(updateProfile).mockRejectedValue(new Error('Could not save profile'));
  },
});
```

This is useful for documenting loading, success, and error states without changing your application code.

#### Handling server-only dependencies

TanStack Start apps often import server-only packages (e.g. database clients, auth libraries) at module scope inside route files. When Storybook loads the route tree, those imports can crash the browser. The integration handles this at three layers:

##### Framework-level mocks (automatic)

The preset already intercepts `@tanstack/react-start`, `@tanstack/react-start/server`, `@tanstack/start-storage-context`, and related TanStack modules. It also replaces `createServerFn()` handlers with mock functions. You do not need to do anything for these.

##### App-level server modules

When your routes import app-specific server code (e.g. `~/db/client`, `~/auth/index.server`), use Storybook's mocking with a `__mocks__` file to prevent the real module (and its Node.js dependencies) from loading in the browser.

**Step 1**: Register the mock in `.storybook/preview.ts`:

```ts
// .storybook/preview.ts — CSF 3

// Prevents postgres (Node-only) from loading in the browser
sb.mock(import('../src/db/client.ts'));

export default {};
```

```ts
// .storybook/preview.ts — CSF Next 🧪

// Prevents postgres (Node-only) from loading in the browser
sb.mock(import('../src/db/client.ts'));

export default definePreview({});
```

**Step 2**: Create `src/db/__mocks__/client.ts` next to the real module. Use only `import type` so no server packages are pulled in:

```ts
// src/db/__mocks__/client.ts

export const db = new Proxy({} as ReturnType<typeof drizzle<typeof schema>>, {
  get: () => () => Promise.resolve([]),
});
```

**Why a `__mocks__` file instead of automocking?**

[Storybook's automocking](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md#automocking) replaces _functions_ but still **evaluates the original module** and its imports. For modules that import `postgres`, `pg`, or other Node.js-only packages, the original module must never be evaluated, because it would crash the browser. A `__mocks__` file is the only approach that completely prevents evaluation of the original module and its dependency chain.

##### Identifying what to mock

Errors like `does not provide an export named 'default'` or `AsyncLocalStorage is not defined` mean a server-only module reached the browser.

The fix is to mock the **server module itself**, not the component or route that uses it. For example, if `Dashboard.tsx` imports `~/auth/session`, and `~/auth/session` imports `~/db/client`, and `~/db/client` imports `postgres` — mock `~/db/client`.
The Node.js dependency (`postgres`) is the smoking gun; mock the closest module to it that you control.

To find that module, walk the error stack trace from top to bottom and stop at the first import you wrote yourself. Then add a [`__mocks__` file](#app-level-server-modules) for it.

Two cases where you do _not_ need a mock:

- The module is from `@tanstack/*` — already handled by the framework preset. Make sure you are on the latest `@storybook/tanstack-react`.
- The module only imports `createServerFn` — already mocked. The error is coming from another import in the same file.

### TanStack Query

You can use this framework together with [TanStack Query](https://tanstack.com/query) to provide a working QueryClient in Storybook and seed query data per story.

#### Project setup

TanStack Query is not automatically set up. The recommended approach is to create a single [`QueryClient`](https://tanstack.com/query/latest/docs/reference/QueryClient) in your preview file, clear it between stories via [`beforeEach`](https://storybook.js.org/docs/writing-tests/interaction-testing.md#beforeeach), and share the same instance through both `parameters.tanstack.router.context` and a `QueryClientProvider` decorator.

```tsx
// .storybook/preview.tsx — CSF 3

// 👇 Create a new QueryClient
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: false,
      staleTime: Infinity,
    },
  },
});

const preview: Preview = {
  beforeEach: () => {
    // 👇 Clear the cache between stories so each story starts fresh
    queryClient.clear();
  },
  parameters: {
    tanstack: {
      router: {
        // 👇 Make queryClient available in stories' beforeEach via ctx.context.queryClient
        context: { queryClient },
      },
    },
  },
  decorators: [
    (Story) => (
      // 👇 Provide the QueryClient to all stories
      
        
      
    ),
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// 👇 Create a new QueryClient
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: false,
      staleTime: Infinity,
    },
  },
});

export default definePreview({
  beforeEach: () => {
    // 👇 Clear the cache between stories so each story starts fresh
    queryClient.clear();
  },
  parameters: {
    tanstack: {
      router: {
        // 👇 Make queryClient available in stories' beforeEach via ctx.context.queryClient
        context: { queryClient },
      },
    },
  },
  decorators: [
    (Story) => (
      // 👇 Provide the QueryClient to all stories
      
        
      
    ),
  ],
});
```

#### Seeding query data per story

In individual stories, use [`beforeEach`](https://storybook.js.org/docs/writing-tests/interaction-testing.md#beforeeach) to call [`setQueryData`](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientsetquerydata) on the shared `QueryClient` before the component renders. Access it from `parameters.tanstack.router.context`:

```ts
// Navbar.stories.ts — CSF 3

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

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

export const Default: Story = {};

export const LoggedIn: Story = {
  beforeEach: async ({ parameters }) => {
    const qc: QueryClient = parameters.tanstack?.router?.context?.queryClient;
    qc?.setQueryData(['currentUser'], {
      id: 'user-1',
      name: 'Ada Lovelace',
    });
  },
};
```

```ts
// Navbar.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Navbar,
});

export const Default = meta.story();

export const LoggedIn = meta.story({
  beforeEach: async ({ parameters }) => {
    const qc: QueryClient = parameters.tanstack?.router?.context?.queryClient;
    qc?.setQueryData(['currentUser'], {
      id: 'user-1',
      name: 'Ada Lovelace',
    });
  },
});
```

## FAQ

### How do I migrate from the `react-vite` framework?

#### Automatic migration

Storybook provides a migration tool for migrating to this framework from the React (Vite) framework, [`@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite.md). To migrate, run this command:

```bash
npx storybook automigrate react-vite-to-tanstack-react
```

This automigration tool performs the following actions:

1. Updates `package.json` files to replace `@storybook/react-vite` with `@storybook/tanstack-react`.
2. Updates `.storybook/main.js|ts` to change the framework property (works with both regular and CSF factories `defineMain` configs).
3. Scans and updates import statements that reference `@storybook/react-vite` in your story files and Storybook configuration files (including `@storybook/react-vite/node` used by CSF factories).
4. Detects manual TanStack Router decorators in `.storybook/preview.*`, the rest of `.storybook/`, and any `*.stories.*` file. When one is found, the CLI offers to copy a ready-to-paste AI prompt to your clipboard that walks an AI assistant through removing the now-redundant decorator.

`@storybook/tanstack-react` already wraps every story in a TanStack Router automatically, so any manual `RouterProvider` / `createRouter` / `createMemoryHistory` / `createRootRoute` decorator should be removed after running the automigration. For stories that need a specific route, use [`parameters.tanstack.router`](#rendering-a-route) instead.

#### Manual migration

First, install the framework:

```shell
npm install --save-dev @storybook/tanstack-react
```

```shell
pnpm add --save-dev @storybook/tanstack-react
```

```shell
yarn add --dev @storybook/tanstack-react
```

Then, update your `.storybook/main.js|ts` to change the framework property:

```diff
// .storybook/main.ts — CSF 3
- import type { StorybookConfig } from '@storybook/react-vite';
+ import type { StorybookConfig } from '@storybook/tanstack-react';

const config: StorybookConfig = {
  // ...
-  framework: '@storybook/react-vite',
+  framework: '@storybook/tanstack-react',
};

export default config;
```

```diff
// .storybook/main.ts — CSF Next 🧪
- import { defineMain } from '@storybook/react-vite/node';
+ import { defineMain } from '@storybook/tanstack-react/node';

export default defineMain({
  // ...
-  framework: '@storybook/react-vite',
+  framework: '@storybook/tanstack-react',
});
```

Then similarly update your `.storybook/preview.*` to import from `@storybook/tanstack-react`:

```diff
// .storybook/preview.tsx — CSF 3
- import type { Preview } from '@storybook/react-vite';
+ import type { Preview } from '@storybook/tanstack-react';

const preview: Preview = {
  //...
};

export default preview;
```

```diff
// .storybook/preview.tsx — CSF Next 🧪
- import { definePreview } from '@storybook/react-vite';
+ import { definePreview } from '@storybook/tanstack-react';

export default definePreview({
  //...
});
```

`@storybook/tanstack-react` already wraps every story in a TanStack Router automatically, so any manual `RouterProvider` / `createRouter` / `createMemoryHistory` / `createRootRoute` decorator should be removed after running the automigration. For stories that need a specific route, use [`parameters.tanstack.router`](#rendering-a-route) instead.

### When should I use `@storybook/tanstack-react` instead of `@storybook/react-vite`?

Use `@storybook/tanstack-react` when your components rely on TanStack Router or TanStack Start APIs and you want Storybook to provide router context, typed route parameters, automatic router mocking, and mocked TanStack Start server-function behavior.

Use [`@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite.md) when your app is a standard React and Vite project without TanStack Router.

### My styles are missing in Storybook

Import your application CSS in `.storybook/preview.*` so it is bundled with the preview:

```ts title=".storybook/preview.tsx"

```

For more information, see the [styling documentation](https://storybook.js.org/docs/configure/styling-and-css.md).

### How do I provide React context providers (e.g. theme, toast, auth) to all stories?

Add [project-level decorators](https://storybook.js.org/docs/writing-stories/decorators.md#global-decorators) to apply providers to all stories.

You can also add [component-level decorators](https://storybook.js.org/docs/writing-stories/decorators.md#component-decorators) to apply providers to all stories for a specific component, or [story-level decorators](https://storybook.js.org/docs/writing-stories/decorators.md#story-decorators) to apply providers to a single story.

### Does `@storybook/tanstack-react` support React Server Components?

No. `@storybook/tanstack-react` runs stories in the browser using a memory-backed router. [React Server Components](https://react.dev/reference/rsc/server-components) require a server runtime and are not supported. If your component is a Server Component, [extract the client-side parts into a Client Component](https://react.dev/reference/rsc/server-components#adding-interactivity-to-server-components) and write stories for that instead.

### Story fails to render with an error about modules not providing a default export

This usually means a server-only module is being imported in the browser. Check the error stack trace to find the module and add a Storybook mock for it as described in [Handling server-only dependencies](#handling-server-only-dependencies).

## API

### Modules

The package exports these additional modules:

#### `@storybook/tanstack-react/react-router`

[TanStack Router](https://tanstack.com/router/latest/docs)-compatible mock implementations used by the framework to provide router behavior in stories. Import from this module when you need direct access to the mock APIs (for example, to assert against navigation spies in tests).

#### `@storybook/tanstack-react/start`

[TanStack Start](https://tanstack.com/start/latest/docs)-compatible mock implementations, including a mocked [`createServerFn()`](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions) implementation. Import from this module when a story or test needs to interact directly with the Start mock layer.

### Options

You can pass an options object for additional configuration if needed:

```ts
// .storybook/main.ts — CSF 3

const config: StorybookConfig = {
  framework: {
    name: '@storybook/tanstack-react',
    options: {
      builder: {
        // Vite builder options
      },
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

export default defineMain({
  framework: {
    name: '@storybook/tanstack-react',
    options: {
      builder: {
        // Vite builder options
      },
    },
  },
});
```

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). Available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).

### Parameters

This framework contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook under the `tanstack.router` namespace:

When `route` is supplied as a plain object, it may also include TanStack route options such as [`head`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#head-method), [`search`](https://tanstack.com/router/latest/docs/guide/search-params#reading-search-params), and [`params.parse`](https://tanstack.com/router/latest/docs/api/router/RouteOptionsType#paramsparse-method).

#### `context`

Type: `Record<string, unknown>`

Router context values injected into the story router.

#### `params`

Type: `ResolveParams<Path>`

Interpolates route params into the current path. When `route` is a typed file route, the type is constrained to the param names declared in that route's path (for example, `{ id: string }` for `/$id`).

#### `path`

Type: `string`

Sets the initial URL path for the story router.

#### `query`

Type: `Record<string, unknown>`

Appends search params to the initial URL.

#### `route`

Type: `AnyRoute | route options object`

Supplies a route instance directly or creates a temporary story route from route options. Storybook extracts the route's React component automatically from the route.

#### `routeOverrides`

Type: `Partial<Record<string, RouteOverrideOptions>>`

Per-route overrides keyed by route ID, applied to the story's route and root route. Use `'__root__'` to target the root route. Each entry can override `loader`, `beforeLoad`, `validateSearch`, `loaderDeps`, and `context`.

#### `useRouterContext`

Type: `({ storyContext }) => RouterContext`

Dynamically computes the router context from the story context. Use this when the router context depends on values that are already available in the story (for example, a `QueryClient` that is loaded by a story loader).

```ts
parameters: {
  tanstack: {
    router: {
      useRouterContext: ({ storyContext }) => ({
        queryClient: storyContext.loaded.queryClient,
      }),
    },
  },
}
```

This is an alternative to [`context`](#context) for cases where the router context needs a React context provider (e.g., TanStack Query's `QueryClientProvider`) that must be rendered in the story before the context value can be accessed.
> Source: https://storybook.js.org/docs/get-started/frameworks/tanstack-react
---

# Storybook for Vue with Vite

Storybook for Vue & Vite is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for [Vue](https://vuejs.org/) applications built with [Vite](https://vitejs.dev/).

## Install

To install Storybook in an existing Vue project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## Configure

Storybook for Vue 3 with Vite is designed to work out of the box with minimal configuration. This section covers configuration options for the framework.

### Extending the Vue application

Storybook creates a [Vue 3 application](https://vuejs.org/api/application.html#application-api) for your component preview. When using global custom components (`app.component`), directives (`app.directive`), extensions (`app.use`), or other application methods, you will need to configure those in the `./storybook/preview.ts` file.

Therefore, Storybook provides you with a `setup` function exported from this package. This function receives your Storybook instance as a callback, which you can interact with and add your custom configuration.

```js title=".storybook/preview.ts"

setup((app) => {
  app.use(MyPlugin);
  app.component('my-component', MyComponent);
  app.mixin({
    // My mixin
  });
});
```

### Using `vue-component-meta`

`vue-component-meta` is only available in Storybook ≥ 8. It is currently an opt-in, but it will become the default in a future version of Storybook.

[`vue-component-meta`](https://github.com/vuejs/language-tools/tree/master/packages/component-meta) is a tool maintained by the Vue team that extracts metadata from Vue components. Storybook can use it to generate the [controls](https://storybook.js.org/docs/essentials/controls.md) for your stories and documentation. It's a more full-featured alternative to `vue-docgen-api` and is recommended for most projects.

If you want to use `vue-component-meta`, you can configure it in your `.storybook/main.js|ts` file:

```ts title=".storybook/main.ts"

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: 'vue-component-meta',
    },
  },
};

export default config;
```

`vue-component-meta` comes with many benefits and enables more documentation features, such as:

#### Support for multiple component types

`vue-component-meta` supports all types of Vue components (including SFC, functional, composition/options API components) from `.vue`, `.ts`, `.tsx`, `.js`, and `.jsx` files.

It also supports both default and named component exports.

#### Prop description and JSDoc tag annotations

To describe a prop, including tags, you can use JSDoc comments in your component's props definition:

```html title="YourComponent.vue"
<script setup lang="ts">
  interface MyComponentProps {
    /** The name of the user */
    name: string;
    /**
     * The category of the component
     *
     * @since 8.0.0
     */
    category?: string;
  }

  withDefaults(defineProps<MyComponentProps>(), {
    category: 'Uncategorized',
  });
</script>
```

The props definition above will generate the following controls:

![Controls generated from props](../../_assets/get-started/vue-component-meta-prop-types-controls.png)

#### Events types extraction

To provide a type for an emitted event, you can use TypeScript types (including JSDoc comments) in your component's `defineEmits` call:

```html title="YourComponent.vue"
<script setup lang="ts">
  type MyChangeEvent = 'change';

  interface MyEvents {
    /** Fired when item is changed */
    (event: MyChangeEvent, item?: Item): void;
    /** Fired when item is deleted */
    (event: 'delete', id: string): void;
    /** Fired when item is upserted into list */
    (e: 'upsert', id: string): void;
  }

  const emit = defineEmits<MyEvents>();
</script>
```

Which will generate the following controls:

![Controls generated from events](../../_assets/get-started/vue-component-meta-event-types-controls.png)

#### Slots types extraction

The slot types are automatically extracted from your component definition and displayed in the controls panel.

```html title="YourComponent.vue"
<template>
  <slot :num="123"></slot>
  <br />
  <slot name="named" str="str"></slot>
  <br />
  <slot name="no-bind"></slot>
  <br />
  <slot name="vbind" v-bind="{ num: 123, str: 'str' }"></slot>
</template>

<script setup lang="ts"></script>
```

If you use `defineSlots`, you can describe each slot using JSDoc comments in your component's slots definition:

```ts
defineSlots<{
  /** Example description for default */
  default(props: { num: number }): any;
  /** Example description for named */
  named(props: { str: string }): any;
  /** Example description for no-bind */
  noBind(props: {}): any;
  /** Example description for vbind */
  vbind(props: { num: number; str: string }): any;
}>();
```

The definition above will generate the following controls:

![Controls generated from slots](../../_assets/get-started/vue-component-meta-slot-types-controls.png)

#### Exposed properties and methods

The properties and methods exposed by your component are automatically extracted and displayed in the [Controls](https://storybook.js.org/docs/essentials/controls.md) panel.

```html title="YourComponent.vue"
<script setup lang="ts">
  import { ref } from 'vue';

  const label = ref('Button');
  const count = ref(100);

  defineExpose({
    /** A label string */
    label,
    /** A count number */
    count,
  });
</script>
```

The definition above will generate the following controls:

![Controls generated from exposed properties and methods](../../_assets/get-started/vue-component-meta-exposed-types-controls.png)

#### Override the default configuration

If you're working with a project that relies on [`tsconfig references`](https://www.typescriptlang.org/docs/handbook/project-references.html) to link to other existing configuration files (e.g., `tsconfig.app.json`, `tsconfig.node.json`), we recommend that you update your [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure.md) configuration file and add the following:

```ts title=".storybook/main.ts"

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: {
        plugin: 'vue-component-meta',
        tsconfig: 'tsconfig.app.json',
      },
    },
  },
};

export default config;
```

This is not a limitation of Storybook, but how `vue-component-meta` works. For more information, refer to the appropriate [GitHub issue](https://github.com/vuejs/language-tools/issues/3896).

Otherwise, you might face missing component types/descriptions or unresolvable import aliases like `@/some/import`.

## FAQ

### How do I manually install the Vue framework?

First, install the framework:

Then, update your `.storybook/main.js|ts` to change the framework property:

### Storybook doesn't work with my Vue 2 project

[Vue 2 entered End of Life](https://v2.vuejs.org/lts/) (EOL) on December 31st, 2023, and is no longer maintained by the Vue team. As a result, Storybook no longer supports Vue 2. We recommend you upgrade your project to Vue 3, which Storybook fully supports. If that's not an option, you can still use Storybook with Vue 2 by installing the latest version of Storybook 7 with the following command:

```shell
npx storybook@^7 init
```

```shell
pnpm dlx storybook@^7 init
```

```shell
yarn dlx storybook@^7 init
```

## API

### Options

You can pass an options object for additional configuration if needed:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).

#### `docgen`

Type: `'vue-docgen-api' | 'vue-component-meta' | boolean`

Default: `'vue-docgen-api'`

Since: `8.0`

Choose which docgen tool to use when generating controls for your components. See [Using `vue-component-meta`](#using-vue-component-meta) for more information.

Set to `false` to disable docgen processing entirely for improved build performance.

```ts title=".storybook/main.ts"

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: false, // Disable docgen for better performance
    },
  },
};

export default config;
```

##### When to disable docgen

Disabling docgen can improve build performance for large projects, but [argTypes won't be inferred automatically](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference), which will prevent features like [Controls](https://storybook.js.org/docs/essentials/controls.md) and [docs](https://storybook.js.org/docs/writing-docs/autodocs.md) from working as expected. To use those features, you will need to [define `argTypes` manually](https://storybook.js.org/docs/api/arg-types.md#manually-specifying-argtypes).
> Source: https://storybook.js.org/docs/get-started/frameworks/vue3-vite
---

# Storybook for Web components with Vite

Storybook for Web components & Vite is a [framework](https://storybook.js.org/docs/contribute/framework.md) that makes it easy to develop and test UI components in isolation for applications using [Web components](https://www.webcomponents.org/introduction) built with [Vite](https://vitejs.dev/).

## Install

To install Storybook in an existing project, run this command in your project's root directory:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

You can then get started [writing stories](https://storybook.js.org/docs/get-started/whats-a-story.md), [running tests](https://storybook.js.org/docs/writing-tests.md) and [documenting your components](https://storybook.js.org/docs/writing-docs.md). For more control over the installation process, refer to the [installation guide](https://storybook.js.org/docs/get-started/install.md).

### Requirements

## Run Storybook

To run Storybook for a particular project, run the following:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

To build Storybook, run:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You will find the output in the configured `outputDir` (default is `storybook-static`).

## FAQ

### How do I manually install the Web Components framework?

First, install the framework:

Then, update your `.storybook/main.js|ts` to change the framework property:

## API

### Options

You can pass an options object for additional configuration if needed:

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder). For this framework, available options can be found in the [Vite builder docs](https://storybook.js.org/docs/builders/vite.md).
> Source: https://storybook.js.org/docs/get-started/frameworks/web-components-vite
---

# What's a story?

A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the “interesting” states a component can support.

When you installed Storybook, the CLI created example components that demonstrate the types of components you can build with Storybook: Button, Header, and Page.

Each example component has a set of stories that show the states it supports. You can browse the stories in the UI and see the code behind them in files that end with `.stories.js|ts`. The stories are written in [Component Story Format](https://storybook.js.org/docs/api/csf.md) (CSF), an ES6 modules-based standard for writing component examples.

Let’s start with the `Button` component. A story is an object that describes how to render the component in question. Here’s how to render `Button` in the “primary” state and export a story called `Primary`.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

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

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});
```

![Button story with args](../_assets/get-started/example-button-args.png)

View the rendered `Button` by clicking on it in the Storybook sidebar. Note how the values specified in [`args`](https://storybook.js.org/docs/writing-stories/args.md) are used to render the component and match those represented in the [Controls](https://storybook.js.org/docs/essentials/controls.md) panel. Using `args` in your stories has additional benefits:

- `Button`'s callbacks are logged into the [Actions](https://storybook.js.org/docs/essentials/actions.md) panel. Click to try it.
- `Button`'s arguments are dynamically editable in the Controls panel. Adjust the controls.

## Working with stories

Storybook makes it easy to work on one component in one state (aka a story) at a time. When you edit a component's code or its stories, Storybook will instantly re-render in the browser. No need to refresh manually.

### Create a new story

If you're working on a component that does not yet have any stories, you can click the ➕ button in the sidebar to search for your component and have a basic story created for you.

You can also create a story file for your new story. We recommend copy/pasting an existing story file next to the component source file, then adjusting it for your component.

If you're working on a component that already has other stories, you can use the [Controls panel](https://storybook.js.org/docs/essentials/controls.md) to adjust the value of a control and then save those changes as a new story.

Or, if you prefer, edit the story file's code to add a new named export for your story:

### Edit a story

Using the [Controls panel](https://storybook.js.org/docs/essentials/controls.md), update a control's value for a story. You can then save the changes to the story and the story file's code will be updated for you.

Of course, you can always update the story's code directly too:

Stories are also helpful for checking that the UI continues to look correct as you make changes. The `Button` component has four stories that show it in different use cases. View those stories now to confirm that your change to `Primary` didn’t introduce unintentional bugs in the other stories.

Checking component’s stories as you develop helps prevent accidental regressions. [Tools that integrate with Storybook can automate this](https://storybook.js.org/docs/writing-tests.md) for you.

Now that we’ve seen the basic anatomy of a story let’s see how we use Storybook’s UI to develop stories.
> Source: https://storybook.js.org/docs/get-started/whats-a-story
---

# Browse Stories

Last chapter, we learned that stories correspond with discrete component states. This chapter demonstrates how to use Storybook as a workshop for building components.

## Sidebar and Preview

A `*.stories.js|ts|svelte` file defines all the stories for a component. Each story has a corresponding sidebar item. When you click on a story, it renders in an isolated preview iframe.

The sidebar contains three areas: sidebar search, story explorer, and [testing widget](https://storybook.js.org/docs/writing-tests.md). Try the sidebar search to find a story by name. Navigate between stories by clicking on them in the explorer. Run component tests for all stories using the widget at the bottom of the sidebar.

Or use keyboard shortcuts. Click on the Storybook menu to see a list of available shortcuts.

![Storybook keyboard shortcuts examples](../_assets/get-started/storybook-keyboard-shortcuts.png)

Storybook supports fast keyboard navigation between landmark regions. Press <kbd>F6</kbd> and <kbd>Shift+F6</kbd> to navigate between the sidebar, toolbar, preview, and addons panel.

## Toolbar

Storybook ships with time-saving tools built-in. The toolbar contains tools that allow you to adjust how the story renders in the Canvas:

- 🔍 Zooming visually scales the component so you can check the details.
- 🖼 Background changes the rendered background behind your component so you can verify how your component renders in different visual contexts.
- 📐 Grid renders your component on top of a grid layout so you can verify if your component is aligned correctly.
- 📏 Measure toggles a measurement overlay to help you inspect the dimensions of components.
- 🎚️ Outline displays the component's bounding box so you can verify if your component is positioned correctly.
- 📱 Viewport renders the component in a variety of dimensions and orientations. It’s ideal for checking the responsiveness of components.

The [“Docs”](https://storybook.js.org/docs/writing-docs.md) page displays auto-generated documentation for components (inferred from the source code). Usage documentation is helpful when sharing reusable components with your team, for example, in an application.

![Storybook keyboard shortcuts examples](../_assets/get-started/mdx-example.png)

The toolbar is customizable. You can use [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md) to quickly toggle themes and languages. Or install Storybook toolbar [addons](https://storybook.js.org/docs/configure/user-interface/storybook-addons.md) from the community to enable advanced workflows.

## Addons

Addons are plugins that extend Storybook's core functionality. You can find them in the addons panel, a reserved place in the Storybook UI below the Canvas. Each tab shows the generated metadata, logs, or static analysis for the selected story by the addon.

![Storybook addon examples](../_assets/get-started/addons.png)

- **Controls** allows you to interact with a component’s args (inputs) dynamically. Experiment with alternate configurations of the component to discover edge cases.
- **Actions** help you verify interactions produce the correct outputs via callbacks. For instance, if you view the “Logged In” story of the `Header` component, we can verify that clicking the “Log out” button triggers the `onLogout` callback, which would be provided by the component that made use of the Header.
- **Interactions** provides a helpful user interface for debugging [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md) with the `play` function.
- **Accessibility** helps you identify [accessibility violations](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) in your components.
- **Visual Tests** lets you pinpoint UI bugs in your local development environment by providing instant feedback directly in Storybook.

Storybook is extensible. Our rich ecosystem of addons helps you test, document, and optimize your stories. You can also create an addon to satisfy your workflow requirements. Read more in the [addons section](https://storybook.js.org/docs/addons.md).

In the next chapter, we'll get your components rendering in Storybook so you can use it to supercharge component development.

## Use stories to build UIs

When building apps, one of the biggest challenges is to figure out if a piece of UI already exists in your codebase and how to use it for the new feature you're building.

Storybook catalogues all your components and their use cases. Therefore, you can quickly browse it to find what you're looking for.

Here's what the workflow looks like:

- 🗃 Use the sidebar to find a suitable component
- 👀 Review its stories to pick a variant that suits your needs
- 📝 Copy/paste the story definition into your app code and wire it up to data

You can access the story definition from the stories file or make it available in your published Storybook using the [Docs addon](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md).

![Docblock source](../_assets/get-started/docblock-source.png)
> Source: https://storybook.js.org/docs/get-started/browse-stories
---

# Setup Storybook

Now that you’ve learned what stories are and how to browse them, let’s demo working on one of your components.

Pick a simple component from your project, like a Button, and write a `.stories.js`, `.stories.ts`, or `.stories.svelte` file to go along with it. It might look something like this:

```ts
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 This default export determines where your story goes in the story list
const meta = {
  component: YourComponent,
} satisfies Meta<typeof YourComponent>;

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

export const Basic: Story = {
  args: {
    //👇 The args you need here will depend on your component
  },
};
```

```ts
// YourComponent.stories.ts|tsx — CSF Next 🧪

//👇 This default export determines where your story goes in the story list
const meta = preview.meta({
  component: YourComponent,
});

export const Basic = meta.story({
  args: {
    //👇 The args you need here will depend on your component
  },
});
```

Go to your Storybook to view the rendered component. It’s OK if it looks a bit unusual right now.

Depending on your technology stack, you also might need to configure the Storybook environment further.

## Render component styles

Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes, things won’t “look right” out of the box.

You may have to configure your CSS tooling for Storybook’s rendering environment. Here are some setup guides for popular tools in the community.

- [Tailwind](https://storybook.js.org/recipes/tailwindcss/)
- [Material UI](https://storybook.js.org/recipes/@mui/material/)
- [Vuetify](https://storybook.js.org/recipes/vuetify/)
- [Styled Components](https://storybook.js.org/recipes/styled-components/)
- [Emotion](https://storybook.js.org/recipes/@emotion/styled/)
- [Sass](https://storybook.js.org/recipes/sass/)
- [Bootstrap](https://storybook.js.org/recipes/bootstrap/)
- [Less](https://storybook.js.org/recipes/less/)
- [Vanilla-extract](https://storybook.js.org/recipes/@vanilla-extract/css/)

Don't see the tool that you're looking for? Check out the [styling and css](https://storybook.js.org/docs/configure/styling-and-css.md) page for more details.

## Configure Storybook for your stack

Storybook comes with a permissive [default configuration](https://storybook.js.org/docs/configure.md). It attempts to customize itself to fit your setup. But it’s not foolproof.

Your project may have additional requirements before components can be rendered in isolation. This warrants customizing configuration further. There are three broad categories of configuration you might need.

<details>
<summary>Build configuration like Webpack and Babel</summary>

If you see errors on the CLI when you run the `yarn storybook` command, you likely need to make changes to Storybook’s build configuration. Here are some things to try:

- [Presets](https://storybook.js.org/docs/addons/addon-types.md) bundle common configurations for various technologies into Storybook. In particular, presets exist for Create React App and Ant Design.
- Specify a custom [Babel configuration](https://storybook.js.org/docs/configure/integration/compilers.md#babel) for Storybook. Storybook automatically tries to use your project’s config if it can.
- Adjust the [Webpack configuration](https://storybook.js.org/docs/builders/webpack.md) that Storybook uses. Try patching in your own configuration if needed.

</details>

<details>
<summary>Runtime configuration</summary>

If Storybook builds but you see an error immediately when connecting to it in the browser, in that case, chances are one of your input files is not compiling/transpiling correctly to be interpreted by the browser. Storybook supports evergreen browsers, but you may need to check the Babel and Webpack settings (see above) to ensure your component code works correctly.

</details>

<details id="component-context" name="component-context">
<summary>Component context</summary>

If a particular story has a problem rendering, often it means your component expects a specific environment is available to the component.

A common frontend pattern is for components to assume that they render in a specific “context” with parent components higher up the rendering hierarchy (for instance, theme providers).

Use [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) to “wrap” every story in the necessary context providers. The [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file allows you to customize how components render in Canvas, the preview iframe. This file can be written in JavaScript (`preview.jsx`) or TypeScript (`preview.tsx`). See how you can wrap every component rendered in Storybook with [Styled Components](https://styled-components.com/) `ThemeProvider`, [Vue's Vuetify](https://vuetifyjs.com/en/), Svelte's [Bits UI](https://bits-ui.com/) `BitsConfig`, or with an Angular theme provider component in the example below.

Use [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) to “wrap” every story in the necessary context providers. The [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file allows you to customize how components render in Canvas, the preview iframe. This file can be written in JavaScript (`preview.js`) or TypeScript (`preview.ts`). See how you can wrap every component rendered in Storybook with [Styled Components](https://styled-components.com/) `ThemeProvider`, [Vue's Vuetify](https://vuetifyjs.com/en/), Svelte's [Bits UI](https://bits-ui.com/) `BitsConfig`, or with an Angular theme provider component in the example below.

```tsx
// .storybook/preview.tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const preview: Preview = {
  decorators: [
    (Story) => (
      
        
        
      
    ),
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [
    (Story) => (
      
        
        
      
    ),
  ],
});
```

</details>

## Load assets and resources

We recommend serving external resources and assets requested in your components statically with Storybook. It ensures that assets are always available to your stories. Read our [documentation](https://storybook.js.org/docs/configure/integration/images-and-assets.md) to learn how to host static files with Storybook.
> Source: https://storybook.js.org/docs/get-started/setup
---

# Conclusion

Congratulations! You learned the basics. Storybook is the most popular tool for UI component development and documentation. You’ll be able to transfer these skills to thousands of companies that use Storybook to build UIs including GitHub, Airbnb, and Stripe.

If you’d like to learn workflows for building app UIs with Storybook, check out our in-depth guides over at the [tutorials](https://storybook.js.org/tutorials/) page. Continue reading for detailed information on how to use Storybook APIs.

- [How to write stories](https://storybook.js.org/docs/writing-stories.md)
- [How to document components and design systems](https://storybook.js.org/docs/writing-docs.md)
- [View example Storybooks from leading companies](https://storybook.js.org/showcase)
> Source: https://storybook.js.org/docs/get-started/conclusion
---

# How to write stories

A story captures the rendered state of a UI component. It's an object with annotations that describe the component's behavior and appearance given a set of arguments.

Storybook uses the generic term arguments (args for short) when talking about React’s `props`, Vue’s `props`, Angular’s `@Input`, and other similar concepts.

## Where to put stories

A component’s stories are defined in a story file that lives alongside the component file. The story file is for development-only, and it won't be included in your production bundle. In your filesystem, it looks something like this:

```
components/
├─ Button/
│  ├─ Button.js | ts | jsx | tsx | vue | svelte
│  ├─ Button.stories.js | ts | jsx | tsx | svelte
```

## Component Story Format

We define stories according to the [Component Story Format](https://storybook.js.org/docs/api/csf.md) (CSF), an ES6 module-based standard that is easy to write and portable between tools.

The key ingredients are the meta (or [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_the_default_export)) that describes the component, and [named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_named_exports) that describe the stories.

### Default export

The _default_ export metadata controls how Storybook lists your stories and provides information used by addons. For example, here’s the meta (or default export) for a story file `Button.stories.js|ts`:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});
```

Starting with Storybook version 7.0, story titles are analyzed statically as part of the build process. The _default_ export must contain a `title` property that can be read statically or a `component` property from which an automatic title can be computed. Using the `id` property to customize your story URL must also be statically readable.

### Defining stories

Use the _named_ exports of a CSF file to define your component’s stories. We recommend you use UpperCamelCase for your story exports. Here’s how to render `Button` in the “primary” state and export a story called `Primary`.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

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

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});
```

#### Custom rendering

By default, stories will render the component defined in the meta (or default export), with the `args` passed to it. If you need to render something else, you can provide a function to the `render` property that returns the desired output.

For example, if you want to render a `Button` inside an `Alert`, you can define a custom render function like this:

```tsx
// Button.stories.tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

type Story = StoryObj<typeof meta>;

export const PrimaryInAlert: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
  render: (args) => (
    
      Alert text
      
    
  ),
};
```

```tsx
// Button.stories.tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const PrimaryInAlert = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
  render: (args) => (
    
      Alert text
      
    
  ),
});
```

Note how the `render` function spreads `args` onto the Button component. This ensures that features like [Controls](https://storybook.js.org/docs/essentials/controls.md) will work as expected, allowing you to dynamically change the Button's properties in the Storybook UI.

You can re-use the same render function across stories by applying it at the meta level:

```tsx
// Button.stories.tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: Button,
  render: (args) => (
    
      Alert text
      
    
  ),
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

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

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

```tsx
// Button.stories.tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  render: (args) => (
    
      Alert text
      
    
  ),
});

export const DefaultInAlert = meta.story({
  args: {
    label: 'Button',
  },
});

export const PrimaryInAlert = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});
```

Whatever you define at the meta level can be overridden at the story level, so you can still customize the rendering of individual stories if needed.

Finally, `render` functions receive a second `context` argument, which contains all other details for the story, including [`parameters`](https://storybook.js.org/docs/writing-stories/parameters.md), [`globals`](https://storybook.js.org/docs/essentials/toolbars-and-globals.md), and more.

#### Working with React Hooks

[React Hooks](https://react.dev/reference/react) are convenient helper methods to create components using a more streamlined approach. You can use them while creating your component's stories if you need them, although you should treat them as an advanced use case. We **recommend** [args](https://storybook.js.org/docs/writing-stories/args.md) as much as possible when writing your own stories. As an example, here’s a story that uses React Hooks to change the button's state:

```tsx
// Button.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

const ButtonWithHooks = () => {
  // Sets the hooks for both the label and primary props
  const [value, setValue] = useState('Secondary');
  const [isPrimary, setIsPrimary] = useState(false);

  // Sets a click handler to change the label's value
  const handleOnChange = () => {
    if (!isPrimary) {
      setIsPrimary(true);
      setValue('Primary');
    }
  };
  return ;
};

export const Primary = {
  render: () => ,
} satisfies Story;
```

```tsx
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

const ButtonWithHooks = () => {
  // Sets the hooks for both the label and primary props
  const [value, setValue] = useState('Secondary');
  const [isPrimary, setIsPrimary] = useState(false);

  // Sets a click handler to change the label's value
  const handleOnChange = () => {
    if (!isPrimary) {
      setIsPrimary(true);
      setValue('Primary');
    }
  };
  return ;
};

export const Primary = meta.story({
  render: () => ,
});
```

### Rename stories

By default, Storybook uses the name of the story export as the basis for the story name. However, you can customize the name of your story by adding a `name` property to the story object. This is useful when you want to provide a more descriptive or user-friendly name for your story.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const Primary: Story = {
  // 👇 Rename this story
  name: 'I am the primary',
  args: {
    label: 'Button',
    primary: true,
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  // 👇 Rename this story
  name: 'I am the primary',
  args: {
    label: 'Button',
    primary: true,
  },
});
```

Your story will now be shown in the sidebar with the given text.

<a id="using-args" />

## How to write stories

A story is an object that describes how to render a component. You can have multiple stories per component, and those stories can build upon one another. For example, we can add Secondary and Tertiary stories based on our Primary story from above.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const Primary: Story = {
  args: {
    backgroundColor: '#ff0',
    label: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    ...Primary.args,
    label: '😄👍😍💯',
  },
};

export const Tertiary: Story = {
  args: {
    ...Primary.args,
    label: '📚📕📈🤓',
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    backgroundColor: '#ff0',
    label: 'Button',
  },
});

export const Secondary = meta.story({
  args: {
    ...Primary.input.args,
    label: '😄👍😍💯',
  },
});

export const Tertiary = meta.story({
  args: {
    ...Primary.input.args,
    label: '📚📕📈🤓',
  },
});
```

What’s more, you can import `args` to reuse when writing stories for other components, and it's helpful when you’re building composite components. For example, if we make a `ButtonGroup` story, we might remix two stories from its child component `Button`.

```ts
// ButtonGroup.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 Imports the Button stories

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

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

export const Pair: Story = {
  args: {
    buttons: [{ ...ButtonStories.Primary.args }, { ...ButtonStories.Secondary.args }],
    orientation: 'horizontal',
  },
};
```

```ts
// ButtonGroup.stories.ts|tsx — CSF Next 🧪

//👇 Imports the Button stories

const meta = preview.meta({
  component: ButtonGroup,
});

export const Pair = meta.story({
  args: {
    buttons: [{ ...ButtonStories.Primary.input.args }, { ...ButtonStories.Secondary.input.args }],
    orientation: 'horizontal',
  },
});
```

When Button’s signature changes, you only need to change Button’s stories to reflect the new schema, and ButtonGroup’s stories will automatically be updated. This pattern allows you to reuse your data definitions across the component hierarchy, making your stories more maintainable.

That’s not all! Each of the args from the story function are live editable using Storybook’s [Controls](https://storybook.js.org/docs/essentials/controls.md) panel. It means your team can dynamically change components in Storybook to stress test and find edge cases.

You can also use the Controls panel to edit or save a new story after adjusting its control values.

Addons can enhance args. For instance, [Actions](https://storybook.js.org/docs/essentials/actions.md) auto-detects which args are callbacks and appends a logging function to them. That way, interactions (like clicks) get logged in the actions panel.

### Using the play function

Storybook's `play` function is a convenient helper methods to test component scenarios that otherwise require user intervention. They're small code snippets that execute once your story renders. For example, suppose you wanted to validate a form component, you could write the following story using the `play` function to check how the component responds when filling in the inputs with information:

```ts
// LoginForm.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: LoginForm,
} satisfies Meta<typeof LoginForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const EmptyForm: Story = {};

export const FilledForm: Story = {
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};
```

```ts
// LoginForm.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: LoginForm,
});

export const EmptyForm = meta.story();

export const FilledForm = meta.story({
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
});
```

You can interact with and debug your story's play function in the [interactions panel](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests).

### Using parameters

Parameters are Storybook’s method of defining static metadata for stories. A story’s parameters can be used to provide configuration to various addons at the level of a story or group of stories.

For instance, suppose you wanted to test your Button component against a different set of backgrounds than the other components in your app. You might add a component-level `backgrounds` parameter:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      options: {},
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      options: {},
    },
  },
});
```

![Parameters background color](../_assets/writing-stories/parameters-background-colors.png)

This parameter would instruct the backgrounds feature to reconfigure itself whenever a Button story is selected. Most features and addons are configured via a parameter-based API and can be influenced at a [global](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters), [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters), and [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level.

### Using decorators

Decorators are a mechanism to wrap a component in arbitrary markup when rendering a story. Components are often created with assumptions about ‘where’ they render. Your styles might expect a theme or layout wrapper, or your UI might expect specific context or data providers.

A simple example is adding padding to a component’s stories. Accomplish this using a decorator that wraps the stories in a `div` with padding, like so:

```tsx
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
} satisfies Meta<typeof Button>;

export default meta;
```

```tsx
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
});
```

Decorators [can be more complex](https://storybook.js.org/docs/writing-stories/decorators.md#context-for-mocking) and are often provided by [addons](https://storybook.js.org/docs/configure/user-interface/storybook-addons.md). You can also configure decorators at the [story](https://storybook.js.org/docs/writing-stories/decorators.md#story-decorators), [component](https://storybook.js.org/docs/writing-stories/decorators.md#component-decorators) and [global](https://storybook.js.org/docs/writing-stories/decorators.md#global-decorators) level.

## Stories for two or more components

Sometimes you may have two or more components created to work together. For instance, if you have a parent `List` component, it may require child `ListItem` components.

```ts
// List.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

// Always an empty list, not super interesting
export const Empty: Story = {};
```

```ts
// List.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: List,
});

// Always an empty list, not super interesting
export const Empty = meta.story();
```

In such cases, it makes sense to [customize the rendering](#custom-rendering) to output the `List` component with different numbers of `ListItem` children.

```tsx
// List.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const Empty: Story = {};

/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.js.org/docs/api/csf
 * to learn how to use render functions.
 */
export const OneItem: Story = {
  render: (args) => (
    
      
    
  ),
};

export const ManyItems: Story = {
  render: (args) => (
    
      
      
      
    
  ),
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: List,
});

export const Empty = meta.story();

/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.js.org/docs/api/csf
 * to learn how to use render functions.
 */
export const OneItem = meta.story({
  render: (args) => (
    
      
    
  ),
});

export const ManyItems = meta.story({
  render: (args) => (
    
      
      
      
    
  ),
});
```

You can also reuse _story data_ from the child `ListItem` in your `List` component. That’s easier to maintain because you don’t have to update it in multiple places.

```tsx
// List.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 We're importing the necessary stories from ListItem

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

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

export const ManyItems: Story = {
  render: (args) => (
    
      
      
      
    
  ),
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

//👇 We're importing the necessary stories from ListItem

const meta = preview.meta({
  component: List,
});

export const ManyItems = meta.story({
  render: (args) => (
    
      
      
      
    
  ),
});
```

Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build even more complex composite components. For more discussion, see the [multi component stories](https://storybook.js.org/docs/writing-stories/stories-for-multiple-components.md) workflow documentation.
> Source: https://storybook.js.org/docs/writing-stories
---

# Args

A story is a component with a set of arguments that define how the component should render. “Args” are Storybook’s mechanism for defining those arguments in a single JavaScript object. Args can be used to dynamically change props, slots, styles, inputs, etc. It allows Storybook and its addons to live edit components. You _do not_ need to modify your underlying component code to use args.

When an arg’s value changes, the component re-renders, allowing you to interact with components in Storybook’s UI via addons that affect args.

Learn how and why to write stories in [the introduction](https://storybook.js.org/docs/writing-stories.md). For details on how args work, read on.

## Args object

The `args` object can be defined at the [story](#story-args), [component](#component-args) and [global level](#global-args). It is a JSON serializable object composed of string keys with matching valid value types that can be passed into a component for your framework.

## Story args

To define the args of a single story, use the `args` CSF story key:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

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

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});
```

These args will only apply to the story for which they are attached, although you can [reuse](https://storybook.js.org/docs/writing-stories/build-pages-with-storybook.md#args-composition-for-presentational-screens) them via JavaScript object reuse:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework

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

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

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

export const PrimaryLongName: Story = {
  args: {
    ...Primary.args,
    label: 'Primary with a really long name',
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});

export const PrimaryLongName = meta.story({
  args: {
    ...Primary.input.args,
    label: 'Primary with a really long name',
  },
});
```

In the above example, we use the [object spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) feature of ES 2015.

## Component args

You can also define args at the component level; they will apply to all the component's stories unless you overwrite them. To do so, use the `args` key on the `default` CSF export:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: Button,
  //👇 Creates specific argTypes
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  args: {
    //👇 Now all Button stories will be primary.
    primary: true,
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  //👇 Creates specific argTypes
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  args: {
    //👇 Now all Button stories will be primary.
    primary: true,
  },
});
```

## Global args

You can also define args at the global level; they will apply to every component's stories unless you overwrite them. To do so, define the `args` property in the default export of `preview.*`:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  // The default value of the theme arg for all stories
  args: { theme: 'light' },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  // The default value of the theme arg for all stories
  args: { theme: 'light' },
});
```

For most uses of global args, [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md) are a better tool for defining globally-applied settings, such as a theme. Using globals enables users to change the value with the toolbar menu.

## Args composition

You can separate the arguments to a story to compose in other stories. Here's how you can combine args for multiple stories of the same component.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework

const meta = {
  component: Button,
} 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: {
    ...Primary.args,
    primary: false,
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});

export const Secondary = meta.story({
  args: {
    ...Primary.input.args,
    primary: false,
  },
});
```

If you find yourself re-using the same args for most of a component's stories, you should consider using [component-level args](#component-args).

Args are useful when writing stories for composite components that are assembled from other components. Composite components often pass their arguments unchanged to their child components, and similarly, their stories can be compositions of their child components stories. With args, you can directly compose the arguments:

```ts
// Page.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 Imports all Header stories

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

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

export const LoggedIn: Story = {
  args: {
    ...HeaderStories.LoggedIn.args,
  },
};
```

```ts
// Page.stories.ts|tsx — CSF Next 🧪

//👇 Imports all Header stories

const meta = preview.meta({
  component: Page,
});

export const LoggedIn = meta.story({
  args: {
    ...HeaderStories.LoggedIn.input.args,
  },
});
```

## Args can modify any aspect of your component

You can use args in your stories to configure the component's appearance, similar to what you would do in an application. For example, here's how you could use a `footer` arg to populate a child component:

```tsx
// Page.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & { footer?: string };

const meta = {
  component: Page,
  render: ({ footer, ...args }) => (
    
      <footer>{footer}</footer>
    
  ),
} satisfies Meta;
export default meta;

type Story = StoryObj<typeof meta>;

export const CustomFooter = {
  args: {
    footer: 'Built with Storybook',
  },
} satisfies Story;
```

```tsx
// Page.stories.ts|tsx — CSF Next 🧪

type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & {
  footer?: string;
};

const meta = preview.type<{ args: PagePropsAndCustomArgs }>().meta({
  component: Page,
  render: ({ footer, ...args }) => (
    <Page {...args}>
      <footer>{footer}</footer>
    
  ),
});

export const CustomFooter = meta.story({
  args: {
    footer: 'Built with Storybook',
  },
});
```

## Setting args through the URL

You can also override the set of initial args for the active story by adding an `args` query parameter to the URL. Typically, you would use [Controls](https://storybook.js.org/docs/essentials/controls.md) to handle this. For example, here's how you could set a `size` and `style` arg in the Storybook's URL:

```
?path=/story/avatar--default&args=style:rounded;size:100
```

As a safeguard against [XSS](https://owasp.org/www-community/attacks/xss/) attacks, the arg's keys and values provided in the URL are limited to alphanumeric characters, spaces, underscores, and dashes. Any other types will be ignored and removed from the URL, but you can still use them with the Controls panel and [within your story](#mapping-to-complex-arg-values).

The `args` param is always a set of `key: value` pairs delimited with a semicolon `;`. Values will be coerced (cast) to their respective `argTypes` (which may have been automatically inferred). Objects and arrays are supported. Special values `null` and `undefined` can be set by prefixing with a bang `!`. For example, `args=obj.key:val;arr[0]:one;arr[1]:two;nil:!null` will be interpreted as:

```js
{
  obj: { key: 'val' },
  arr: ['one', 'two'],
  nil: null
}
```

Similarly, special formats are available for dates and colors. Date objects will be encoded as `!date(value)` with value represented as an ISO date string. Colors are encoded as `!hex(value)`, `!rgba(value)` or `!hsla(value)`. Note that rgb(a) and hsl(a) should not contain spaces or percentage signs in the URL.

Args specified through the URL will extend and override any default values of args set on the story.

## Setting args from within a story

Interactive components often need to be controlled by their containing component or page to respond to events, modify their state and reflect those changes in the UI. For example, when a user toggles a switch component, the switch should be checked, and the arg shown in Storybook should reflect the change. To enable this, you can use the `useArgs` API exported by `storybook/preview-api`:

```tsx
// my-component/component.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  title: 'Inputs/Checkbox',
  component: Checkbox,
} satisfies Meta<typeof Checkbox>;
export default meta;

type Story = StoryObj<typeof Checkbox>;

export const Example = {
  args: {
    isChecked: false,
    label: 'Try Me!',
  },
  /**
   * 👇 To avoid linting issues, it is recommended to use a function with a capitalized name.
   * If you are not concerned with linting, you may use an arrow function.
   */
  render: function Render(args) {
    const [{ isChecked }, updateArgs] = useArgs();

    function onChange() {
      updateArgs({ isChecked: !isChecked });
    }

    return ;
  },
} satisfies Story;
```

```tsx
// my-component/component.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  title: 'Inputs/Checkbox',
  component: Checkbox,
});

export const Example = meta.story({
  args: {
    isChecked: false,
    label: 'Try Me!',
  },
  /**
   * 👇 To avoid linting issues, it is recommended to use a function with a capitalized name.
   * If you are not concerned with linting, you may use an arrow function.
   */
  render: function Render(args) {
    const [{ isChecked }, updateArgs] = useArgs();

    function onChange() {
      updateArgs({ isChecked: !isChecked });
    }

    return ;
  },
});
```

If you're using Storybook's hooks API in the story's render function, **do not** mix them with React's hooks such as `useState`, `useEffect`, or `useRef`. This is because side effects and re-rendering triggered by React's hooks do not run through Storybook's hook context, which can cause an error on re-render. To manage state and side effects within a story, you must use Storybook's equivalent hooks, such as `useState`, `useEffect`, and `useRef` from `storybook/preview-api`.

## Mapping to complex arg values

Complex values such as JSX elements cannot be serialized to the manager (e.g., the Controls panel) or synced with the URL. Arg values can be "mapped" from a simple string to a complex type using the `mapping` property in `argTypes` to work around this limitation. It works in any arg but makes the most sense when used with the `select` control type.

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    label: {
      control: { type: 'select' },
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    label: {
      control: { type: 'select' },
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
});
```

Note that `mapping` does not have to be exhaustive. If the arg value is not a property of `mapping`, the value will be used directly. Keys in `mapping` always correspond to arg _values_, not their index in the `options` array.

<details>
<summary>Using args in addons</summary>

If you are [writing an addon](https://storybook.js.org/docs/addons/writing-addons.md) that wants to read or update args, use the `useArgs` hook exported by `storybook/manager-api`:

```js
// my-addon/src/manager.js|ts

const [args, updateArgs, resetArgs] = useArgs();

// To update one or more args:
updateArgs({ key: 'value' });

// To reset one (or more) args:
resetArgs((argNames: ['key']));

// To reset all args
resetArgs();
```

</details>
> Source: https://storybook.js.org/docs/writing-stories/args
---

# Parameters

Parameters are a set of static, named metadata about a story, typically used to control the behavior of Storybook features and addons.

Available parameters are listed in the [parameters API reference](https://storybook.js.org/docs/api/parameters.md#available-parameters).

For example, let’s customize the backgrounds feature via a parameter. We’ll use `parameters.backgrounds` to define which backgrounds appear in the backgrounds toolbar when a story is selected.

## Story parameters

We can set a parameter for a single story with the `parameters` key on a CSF export:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Primary: Story = {
  // 👇 Story-level parameters
  parameters: {
    backgrounds: {
      options: {
        red: { name: 'Red', value: '#f00' },
        green: { name: 'Green', value: '#0f0' },
        blue: { name: 'Blue', value: '#00f' },
      },
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  // 👇 Story-level parameters
  parameters: {
    backgrounds: {
      options: {
        red: { name: 'Red', value: '#f00' },
        green: { name: 'Green', value: '#0f0' },
        blue: { name: 'Blue', value: '#00f' },
      },
    },
  },
});
```

## Component parameters

We can set the parameters for all stories of a component using the `parameters` key on the default CSF export:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      options: {},
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      options: {},
    },
  },
});
```

## Global parameters

We can also set the parameters for **all stories** via the `parameters` export of your [`.storybook/preview.ts|tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file (this is the file where you configure all stories):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#fff' },
        dark: { name: 'Dark', value: '#333' },
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#fff' },
        dark: { name: 'Dark', value: '#333' },
      },
    },
  },
});
```

Setting a global parameter is a common way to configure addons. With backgrounds, you configure the list of backgrounds that every story can render in.

## Rules of parameter inheritance

The way the global, component and story parameters are combined is:

- More specific parameters take precedence (so a story parameter overwrites a component parameter which overwrites a global parameter).
- Parameters are **merged**, so keys are only ever overwritten and never dropped.

The merging of parameters is important. This means it is possible to override a single specific sub-parameter on a per-story basis while retaining most of the parameters defined globally.

If you are defining an API that relies on parameters (e.g., an [**addon**](https://storybook.js.org/docs/addons.md)) it is a good idea to take this behavior into account.
> Source: https://storybook.js.org/docs/writing-stories/parameters
---

# Decorators

A decorator is a way to wrap a story in extra “rendering” functionality. Many addons define decorators to augment your stories with extra rendering or gather details about how your story renders.

When writing stories, decorators are typically used to wrap stories with extra markup or context mocking.

## Wrap stories with extra markup

Some components require a “harness” to render in a useful way. For instance, if a component runs right up to its edges, you might want to space it inside Storybook. Use a decorator to add spacing for all stories of the component.

![Story without padding](../_assets/writing-stories/decorators-no-padding.png)

```tsx
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: YourComponent,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
} satisfies Meta<typeof YourComponent>;

export default meta;
```

```tsx
// YourComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: YourComponent,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
});
```

![Story with padding](../_assets/writing-stories/decorators-padding.png)

## “Context” for mocking

The second argument to a decorator function is the **story context** which contains the properties:

- `args` - the story arguments. You can use some [`args`](https://storybook.js.org/docs/writing-stories/args.md) in your decorators and drop them in the story implementation itself.
- `argTypes`- Storybook's [argTypes](https://storybook.js.org/docs/api/arg-types.md) allow you to customize and fine-tune your stories [`args`](https://storybook.js.org/docs/writing-stories/args.md).
- `globals` - Storybook-wide [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals). In particular you can use the [toolbars feature](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#global-types-and-the-toolbar-annotation) to allow you to change these values using Storybook’s UI.
- `hooks` - Storybook's API hooks (e.g., `useArgs`, `useGlobals`). These are available in both decorators and story render functions. When using these hooks in a render function alongside framework hooks (e.g., React's `useState`, `useEffect`), use Storybook's hook equivalents from `storybook/preview-api` instead to avoid errors on re-render.
- `parameters`- the story's static metadata, most commonly used to control Storybook's behavior of features and addons.
- `viewMode`- Storybook's current active window (e.g., canvas, docs).

This context can be used to adjust the behavior of your decorator based on the story's arguments or other metadata. For example, you could create a decorator that allows you to optionally apply a layout to the story, by defining `parameters.pageLayout = 'page'` (or `'page-mobile'`):
:

```tsx
// .storybook/preview.tsx — CSF 3

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const preview: Preview = {
  decorators: [
    // 👇 Defining the decorator in the preview file applies it to all stories
    (Story, { parameters }) => {
      // 👇 Make it configurable by reading from parameters
      const { pageLayout } = parameters;
      switch (pageLayout) {
        case 'page':
          return (
            // Your page layout is probably a little more complex than this
            <div className="page-layout">
              
            </div>
          );
        case 'page-mobile':
          return (
            <div className="page-mobile-layout">
              
            </div>
          );
        default:
          // In the default case, don't apply a layout
          return ;
      }
    },
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [
    // 👇 Defining the decorator in the preview file applies it to all stories
    (Story, { parameters }) => {
      // 👇 Make it configurable by reading from parameters
      const { pageLayout } = parameters;
      switch (pageLayout) {
        case 'page':
          return (
            // Your page layout is probably a little more complex than this
            <div className="page-layout">
              
            </div>
          );
        case 'page-mobile':
          return (
            <div className="page-mobile-layout">
              
            </div>
          );
        default:
          // In the default case, don't apply a layout
          return ;
      }
    },
  ],
});
```

For another example, see the section on [configuring the mock provider](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-providers.md#configuring-the-mock-provider), which demonstrates how to use the same technique to change which theme is provided to the component.

### Using decorators to provide data

If your components are “connected” and require side-loaded data to render, you can use decorators to provide that data in a mocked way without having to refactor your components to take that data as an arg. There are several techniques to achieve this. Depending on exactly how you are loading that data. Read more in the [building pages in Storybook](https://storybook.js.org/docs/writing-stories/build-pages-with-storybook.md) section.

## Story decorators

To define a decorator for a single story, use the `decorators` key on a named export:

```tsx
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const Primary: Story = {
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
};
```

```tsx
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
});
```

It is useful to ensure that the story remains a “pure” rendering of the component under test and that any extra HTML or components are used only as decorators. In particular the [Source](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md) Doc Block works best when you do this.

## Component decorators

To define a decorator for all stories of a component, use the `decorators` key of the default CSF export:

```tsx
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
} satisfies Meta<typeof Button>;

export default meta;
```

```tsx
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
});
```

## Global decorators

We can also set a decorator for **all stories** via the `decorators` export of your [`.storybook/preview.ts|tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file (this is the file where you configure all stories):

```tsx
// .storybook/preview.tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const preview: Preview = {
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        
        
      </div>
    ),
  ],
});
```

## Decorator inheritance

Like parameters, decorators can be defined globally, at the component level, and for a single story (as we’ve seen).

All decorators relevant to a story will run in the following order once the story renders:

- Global decorators, in the order they are defined
- Component decorators, in the order they are defined
- Story decorators, in the order they are defined, starting from the innermost decorator and working outwards and up the hierarchy in the same order
> Source: https://storybook.js.org/docs/writing-stories/decorators
---

# Play function

`Play` functions are small snippets of code executed after the story renders. They enable you to interact with your components and test scenarios that otherwise require user intervention.

## Writing stories with the play function

Storybook's `play` functions are small code snippets that run once the story finishes rendering. Aided by the [interactions panel](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests), it allows you to build component interactions and test scenarios that were impossible without user intervention. For example, if you were working on a registration form and wanted to validate it, you could write the following story with the `play` function:

```ts
// RegistrationForm.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

/*
 * See https://storybook.js.org/docs/writing-stories/play-function#working-with-the-canvas
 * to learn more about using the canvas to query the DOM
 */
export const FilledForm: Story = {
  play: async ({ canvas, userEvent }) => {
    const emailInput = canvas.getByLabelText('email', {
      selector: 'input',
    });

    await userEvent.type(emailInput, 'example-email@email.com', {
      delay: 100,
    });

    const passwordInput = canvas.getByLabelText('password', {
      selector: 'input',
    });

    await userEvent.type(passwordInput, 'ExamplePassword', {
      delay: 100,
    });

    const submitButton = canvas.getByRole('button');
    await userEvent.click(submitButton);
  },
};
```

```ts
// RegistrationForm.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: RegistrationForm,
});

/*
 * See https://storybook.js.org/docs/writing-stories/play-function#working-with-the-canvas
 * to learn more about using the canvas to query the DOM
 */
export const FilledForm = meta.story({
  play: async ({ canvas, userEvent }) => {
    const emailInput = canvas.getByLabelText('email', {
      selector: 'input',
    });

    await userEvent.type(emailInput, 'example-email@email.com', {
      delay: 100,
    });

    const passwordInput = canvas.getByLabelText('password', {
      selector: 'input',
    });

    await userEvent.type(passwordInput, 'ExamplePassword', {
      delay: 100,
    });

    const submitButton = canvas.getByRole('button');
    await userEvent.click(submitButton);
  },
});
```

See the [interaction testing documentation](https://storybook.js.org/docs/writing-tests/interaction-testing.md#writing-interaction-tests) for an overview of the available API events.

When Storybook finishes rendering the story, it executes the steps defined within the `play` function, interacting with the component and filling the form's information. All of this without the need for user intervention. If you check your `Interactions` panel, you'll see the step-by-step flow.

## Working with the canvas

Part of the context passed to the `play` function is a `canvas` object. This object allows you to query the DOM of the rendered story. It provides a scoped version of the Testing Library queries, so you can use them as you would in a regular test.

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;
export default meta;

type Story = StoryObj<typeof meta>;

export const ExampleStory: Story = {
  play: async ({ canvas, userEvent }) => {
    // Starts querying from the component's root element
    await userEvent.type(canvas.getByTestId('example-element'), 'something');
    await userEvent.click(canvas.getByRole('button'));
  },
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const ExampleStory = meta.story({
  play: async ({ canvas, userEvent }) => {
    // Starts querying from the component's root element
    await userEvent.type(canvas.getByTestId('example-element'), 'something');
    await userEvent.click(canvas.getByRole('button'));
  },
});
```

If you need to query outside of the canvas (for example, to test a dialog that appears outside of the story root), you can use the `screen` object available from `storybook/test`.

```ts
// Dialog.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Dialog,
} satisfies Meta<typeof Dialog>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Open: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Open dialog' }));

    // Starts querying from the document
    const dialog = screen.getByRole('dialog');
    await expect(dialog).toBeVisible();
  },
};
```

```ts
// Dialog.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Dialog,
});

export const Open = meta.story({
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Open dialog' }));

    // Starts querying from the document
    const dialog = screen.getByRole('dialog');
    await expect(dialog).toBeVisible();
  },
});
```

## Composing stories

Thanks to the [Component Story Format](https://storybook.js.org/docs/api/csf.md), an ES6 module based file format, you can also combine your `play` functions, similar to other existing Storybook features (e.g., [args](https://storybook.js.org/docs/writing-stories/args.md)). For example, if you wanted to verify a specific workflow for your component, you could write the following stories:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;
export default meta;

type Story = StoryObj<typeof meta>;

/*
 * See https://storybook.js.org/docs/writing-stories/play-function#working-with-the-canvas
 * to learn more about using the canvas to query the DOM
 */
export const FirstStory: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.type(canvas.getByTestId('an-element'), 'example-value');
  },
};

export const SecondStory: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.type(canvas.getByTestId('other-element'), 'another value');
  },
};

export const CombinedStories: Story = {
  play: async ({ context, canvas, userEvent }) => {
    // Runs the FirstStory and Second story play function before running this story's play function
    await FirstStory.play(context);
    await SecondStory.play(context);
    await userEvent.type(canvas.getByTestId('another-element'), 'random value');
  },
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

/*
 * See https://storybook.js.org/docs/writing-stories/play-function#working-with-the-canvas
 * to learn more about using the canvas to query the DOM
 */
export const FirstStory = meta.story({
  play: async ({ canvas, userEvent }) => {
    await userEvent.type(canvas.getByTestId('an-element'), 'example-value');
  },
});

export const SecondStory = meta.story({
  play: async ({ canvas, userEvent }) => {
    await userEvent.type(canvas.getByTestId('other-element'), 'another value');
  },
});

export const CombinedStories = meta.story({
  play: async ({ context, canvas, userEvent }) => {
    // Runs the FirstStory and Second story play function before running this story's play function
    await FirstStory.play(context);
    await SecondStory.play(context);
    await userEvent.type(canvas.getByTestId('another-element'), 'random value');
  },
});
```

By combining the stories, you're recreating the entire component workflow and can spot potential issues while reducing the boilerplate code you need to write.
> Source: https://storybook.js.org/docs/writing-stories/play-function
---

# Loaders

Loaders are asynchronous functions that load data for a story and its [decorators](https://storybook.js.org/docs/writing-stories/decorators.md). A story's loaders run before the story renders, and the loaded data injected into the story via its render context.

Loaders can be used to load any asset, lazy load components, or fetch data from a remote API. This feature was designed as a performance optimization to handle large story imports. However, [args](https://storybook.js.org/docs/writing-stories/args.md) is the recommended way to manage story data. We're building up an ecosystem of tools and techniques around Args that might not be compatible with loaded data.

They are an advanced feature (i.e., escape hatch), and we only recommend using them if you have a specific need that other means can't fulfill.

## Fetching API data

Stories are isolated component examples that render internal data defined as part of the story or alongside the story as [args](https://storybook.js.org/docs/writing-stories/args.md).

Loaders are helpful when you need to load story data externally (e.g., from a remote API). Consider the following example that fetches a todo item to display in a todo list:

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.js.org/docs/api/csf
 * to learn how to use render functions.
 */
const meta = {
  component: TodoItem,
  render: (args, { loaded: { todo } }) => ,
} satisfies Meta<typeof TodoItem>;

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

export const Primary: Story = {
  loaders: [
    async () => ({
      todo: await (await fetch('https://jsonplaceholder.typicode.com/todos/1')).json(),
    }),
  ],
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.js.org/docs/api/csf
 * to learn how to use render functions.
 */
const meta = preview.meta({
  component: TodoItem,
  render: (args, { loaded: { todo } }) => ,
});

export const Primary = meta.story({
  loaders: [
    async () => ({
      todo: await (await fetch('https://jsonplaceholder.typicode.com/todos/1')).json(),
    }),
  ],
});
```

The response obtained from the remote API call is combined into a `loaded` field on the story context, which is the second argument to a story function. For example, in React, the story's args were spread first to prioritize them over the static data provided by the loader. With other frameworks (e.g., Angular), you can write your stories as you'd usually do.

## Global loaders

We can also set a loader for **all stories** via the `loaders` export of your [`.storybook/preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file (this is the file where you configure all stories):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  loaders: [
    async () => ({
      currentUser: await (await fetch('https://jsonplaceholder.typicode.com/users/1')).json(),
    }),
  ],
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  loaders: [
    async () => ({
      currentUser: await (await fetch('https://jsonplaceholder.typicode.com/users/1')).json(),
    }),
  ],
});
```

In this example, we load a "current user" available as `loaded.currentUser` for all stories.

## Loader inheritance

Like [parameters](https://storybook.js.org/docs/writing-stories/parameters.md), loaders can be defined globally, at the component level, and for a single story (as we’ve seen).

All loaders, defined at all levels that apply to a story, run before the story renders in Storybook's canvas.

- All loaders run in parallel
- All results are the `loaded` field in the story context
- If there are keys that overlap, "later" loaders take precedence (from lowest to highest):
  - Global loaders, in the order they are defined
  - Component loaders, in the order they are defined
  - Story loaders, in the order they are defined
> Source: https://storybook.js.org/docs/writing-stories/loaders
---

# Tags

Tags allow you to control which stories are included in your Storybook, enabling many different uses of the same total set of stories. For example, you can use tags to include/exclude tests from the [test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md#run-tests-for-a-subset-of-stories). For more complex use cases, see the [recipes](#recipes) section, below.

## Built-in tags

The following tags are available in every Storybook project:

| Tag        | Applied by default? | Description                                                                                                                                                                                                                                                   |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dev`      | Yes                 | Stories tagged with `dev` are rendered in Storybook's sidebar.                                                                                                                                                                                                |
| `manifest` | Yes                 | Stories and docs tagged with `manifest` are included in the [component or docs manifests](https://storybook.js.org/docs/ai/manifests.md) (Currently React-only).                                                                                                                        |
| `test`     | Yes                 | Stories tagged with `test` are included in [test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md#run-tests-for-a-subset-of-stories) or [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#including-excluding-or-skipping-tests) runs. |
| `autodocs` | No                  | Stories tagged with `autodocs` are included in the [docs page](https://storybook.js.org/docs/writing-docs/autodocs.md). If a CSF file does not contain at least one story tagged with `autodocs`, that component will not generate a docs page.                                         |
| `play-fn`  | No                  | Applied automatically to stories with a [play function](https://storybook.js.org/docs/writing-stories/play-function.md) defined.                                                                                                                                                                         |
| `test-fn`  | No                  | Applied automatically to tests defined using the [experimental `.test` method on CSF Factories](https://storybook.js.org/docs/api/csf/csf-next.md#storytest).                                                                                                                           |

The `dev`, `manifest`, and `test` tags are automatically, implicitly applied to every story in your Storybook project.

## Custom tags

You're not limited to the built-in tags. Custom tags enable a flexible layer of categorization on top of Storybook's sidebar hierarchy. Sample uses might include:

- Status, such as `experimental`, `new`, `stable`, or `deprecated`
- User persona, such as `admin`, `user`, or `developer`
- Component/code ownership

There are two ways to create a custom tag:

1. Apply it to a story, component (meta), or project (`.storybook/preview.*`) as described below.
2. Define it in your Storybook configuration file (`.storybook/main.*`) to provide more configuration options, like default [filter selection](#filtering-the-sidebar-by-tags).

For example, to define an "experimental" tag that is excluded by default in the sidebar, you can add this to your Storybook config:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Define a custom tag named "experimental"
    experimental: {
      defaultFilterSelection: 'exclude', // Or 'include'
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Define a custom tag named "experimental"
    experimental: {
      defaultFilterSelection: 'exclude', // Or 'include'
    },
  },
});
```

If `defaultFilterSelection` is set to `include`, stories with this tag are selected as included in the filter menu. If set to `exclude`, stories with this tag are selected as excluded, and must be explicitly included by selecting the tag in the sidebar filter menu. If not set, the tag has no default selection.

You can also use the [`tags` configuration](https://storybook.js.org/docs/api/main-config/main-config-tags.md) to alter the configuration of built-in tags.

## Applying tags

A tag can be any static (i.e. not created dynamically) string, either the [built-in tags](#built-in-tags) or [custom tags](#custom-tags) of your own design. To apply tags to a story, assign an array of strings to the `tags` property. Tags may be applied at the project, component (meta), or story levels.

For example, to apply the `autodocs` tag to all stories in your project, you can use `.storybook/preview.*`:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  /*
   * All stories in your project will have these tags applied:
   * - autodocs
   * - dev (implicit default)
   * - test (implicit default)
   */
  tags: ['autodocs'],
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  /*
   * All stories in your project will have these tags applied:
   * - autodocs
   * - dev (implicit default)
   * - test (implicit default)
   */
  tags: ['autodocs'],
});
```

Within a component stories file, you apply tags like so:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  /*
   * All stories in this file will have these tags applied:
   * - autodocs
   * - dev (implicit default, inherited from preview)
   * - test (implicit default, inherited from preview)
   */
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;

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

export const ExperimentalFeatureStory: Story = {
  /*
   * This particular story will have these tags applied:
   * - experimental
   * - autodocs (inherited from meta)
   * - dev (inherited from meta)
   * - test (inherited from meta)
   */
  tags: ['experimental'],
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  /*
   * All stories in this file will have these tags applied:
   * - autodocs
   * - dev (implicit default, inherited from preview)
   * - test (implicit default, inherited from preview)
   */
  tags: ['autodocs'],
});

export const ExperimentalFeatureStory = meta.story({
  /*
   * This particular story will have these tags applied:
   * - experimental
   * - autodocs (inherited from meta)
   * - dev (inherited from meta)
   * - test (inherited from meta)
   */
  tags: ['experimental'],
});
```

## Removing tags

To remove a tag from a story, prefix it with `!`. For example:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, etc.

const meta = {
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
} satisfies Meta<typeof Button>;

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

export const ExperimentalFeatureStory: Story = {
  //👇 For this particular story, remove the inherited `stable` tag and apply the `experimental` tag
  tags: ['!stable', 'experimental'],
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
});

export const ExperimentalFeatureStory = meta.story({
  //👇 For this particular story, remove the inherited `stable` tag and apply the `experimental` tag
  tags: ['!stable', 'experimental'],
});
```

Tags can be removed for all stories in your project (in `.storybook/preview.*`), all stories for a component (in the CSF file meta), or a single story (as above).

## Filtering the sidebar by tags

Both built-in and custom tags are available as filters in Storybook's sidebar. Selecting a tag in the filter causes the sidebar to only show stories with that tag. Selecting multiple tags shows stories that contain any of those tags.

Pressing the Exclude button for a tag in the filter menu excludes stories with that tag from the sidebar. You can exclude multiple tags, and stories with any of those tags will be excluded. You can also mix inclusion and exclusion.

When no tags are selected, all stories are shown.

In this example, the `experimental` tag has been excluded and the Documentation tag (`autodocs`) has been included, so only stories tagged with `autodocs` but not `experimental` are shown.

![Filtering by tags](../_assets/writing-stories/tag-filter.png)

Filtering by tags is a powerful way to focus on a subset of stories, especially in large Storybook projects. When searching, the filter is applied first, so search results are limited to the currently filtered tags.

## Recipes

### Docs-only stories

It can sometimes be helpful to provide example stories for documentation purposes, but you want to keep the sidebar navigation more focused on stories useful for development. By enabling the `autodocs` tag and removing the `dev` tag, a story becomes docs-only: appearing only in the [docs page](https://storybook.js.org/docs/writing-docs/autodocs.md) and not in Storybook's sidebar.

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  /*
   * All stories in this file will:
   * - Be included in the docs page
   * - Not appear in Storybook's sidebar
   */
  tags: ['autodocs', '!dev'],
} satisfies Meta<typeof Button>;
export default meta;
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  /*
   * All stories in this file will:
   * - Be included in the docs page
   * - Not appear in Storybook's sidebar
   */
  tags: ['autodocs', '!dev'],
});
```

### Combo stories, still tested individually

For a component with many variants, like a Button, a grid of those variants all together can be a helpful way to visualize it. But you may wish to test the variants individually. You can accomplish this with tags like so:

```tsx
// Button.stories.tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

type Story = StoryObj<typeof meta>;

export const Variant1: Story = {
  // 👇 This story will not appear in Storybook's sidebar or docs page
  tags: ['!dev', '!autodocs'],
  args: { variant: 1 },
};

export const Variant2: Story = {
  // 👇 This story will not appear in Storybook's sidebar or docs page
  tags: ['!dev', '!autodocs'],
  args: { variant: 2 },
};

export const Combo: Story = {
  // 👇 This story should not be tested, but will appear in the sidebar and docs page
  tags: ['!test'],
  render: () => (
    <>
      
      
    </>
  ),
};
```

```tsx
// Button.stories.tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Variant1 = meta.story({
  // 👇 This story will not appear in Storybook's sidebar or docs page
  tags: ['!dev', '!autodocs'],
  args: { variant: 1 },
});

export const Variant2 = meta.story({
  // 👇 This story will not appear in Storybook's sidebar or docs page
  tags: ['!dev', '!autodocs'],
  args: { variant: 2 },
});

export const Combo = meta.story({
  // 👇 This story should not be tested, but will appear in the sidebar and docs page
  tags: ['!test'],
  render: () => (
    <>
      
      
    </>
  ),
});
```

### Test cases that don't clutter the sidebar

(⚠️ **Experimental**: While this API is available for all tags, the built-in `_test` tag is experimental)

If you're using the [experimental `.test` method on CSF Factories](https://github.com/storybookjs/storybook/discussions/30119), you can alter the default behavior of the `_test` tag to exclude tests from the sidebar by default. This reduces clutter in the sidebar while still allowing you to run tests for all stories, or adjust the filter to show tests when needed.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Adjust the default configuration of this tag
    _test: {
      defaultFilterSelection: 'exclude',
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Adjust the default configuration of this tag
    _test: {
      defaultFilterSelection: 'exclude',
    },
  },
});
```
> Source: https://storybook.js.org/docs/writing-stories/tags
---

# Naming components and hierarchy

Storybook provides a powerful way to organize your stories, giving you the necessary tools to categorize, search, and filter your stories based on your organization's needs and preferences.

## Structure and hierarchy

When organizing your Storybook, there are two methods of structuring your stories: **implicit** and **explicit**. The [implicit method](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#csf-30-auto-titles) involves relying upon the physical location of your stories to position them in the sidebar, while the [explicit method](#naming-stories) involves utilizing the `title` parameter to place the story.

![Storybook sidebar hierarchy](../_assets/writing-stories/naming-hierarchy-sidebar-anatomy.png)

Based on how you structure your Storybook, you can see that the story hierarchy is made up of various parts:

- **Category**: The top-level grouping of stories and documentation pages generated by Storybook
- **Folder**: A mid-level organizational unit that groups components and stories in the sidebar, representing a feature or section of your application
- **Component**: A low-level organizational unit representing the component that the story is testing
- **Docs**: The automatically generated [documentation page](https://storybook.js.org/docs/writing-docs/autodocs.md) for the component
- **Story**: The individual story testing a specific component state

## Naming stories

When creating your stories, you can explicitly use the `title` parameter to define the story's position in the sidebar. It can also be used to [group](#grouping) related components together in an expandable interface to help with Storybook organization providing a more intuitive experience for your users. For example:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
});
```

Yields this:

![Stories hierarchy without paths](../_assets/writing-stories/naming-hierarchy-no-path.png)

## Grouping

It is also possible to group related components in an expandable interface to help with Storybook organization. To do so, use the `/` as a separator:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Button',
  component: Button,
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Button',
  component: Button,
});
```

```ts
// Checkbox.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Checkbox',
  component: Checkbox,
} satisfies Meta<typeof Checkbox>;

export default meta;
```

```ts
// Checkbox.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Checkbox',
  component: Checkbox,
});
```

Yields this:

![Stories hierarchy with paths](../_assets/writing-stories/naming-hierarchy-with-path.png)

## Roots

By default, the top-level grouping will be displayed as “root” in the Storybook UI (i.e., the uppercased, non-expandable items). If you need, you can [configure Storybook](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#roots) and disable this behavior. Useful if you need to provide a streamlined experience for your users; nevertheless, if you have a large Storybook composed of multiple component stories, we recommend naming your components according to the file hierarchy.

## Single-story hoisting

Single-story components (i.e., component stories without **siblings**) whose **display name** exactly matches the component's name (last part of `title`) are automatically hoisted up to replace their parent component in the UI. For example:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Button',
  component: ButtonComponent,
} satisfies Meta<typeof ButtonComponent>;

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

// This is the only named export in the file, and it matches the component name
export const Button: Story = {};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Button',
  component: ButtonComponent,
});

// This is the only named export in the file, and it matches the component name
export const Button = meta.story();
```

![Stories hierarchy with single story hoisting](../_assets/writing-stories/naming-hierarchy-single-story-hoisting.png)

Because story exports are automatically "start cased" (`myStory` becomes `"My Story"`), your component name should match that. Alternatively, you can override the story name using `myStory.storyName = '...'` to match the component name.

## Sorting stories

Out of the box, Storybook sorts stories based on the order in which they are imported. However, you can customize this pattern to suit your needs and provide a more intuitive experience by adding `storySort` to the `options` parameter in your `preview.js` file.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    options: {
      // The `a` and `b` arguments in this function have a type of `import('storybook/internal/types').IndexEntry`. Remember that the function is executed in a JavaScript environment, so use JSDoc for IntelliSense to introspect it.
      storySort: (a, b) =>
        a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }),
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    options: {
      // The `a` and `b` arguments in this function have a type of `import('storybook/internal/types').IndexEntry`. Remember that the function is executed in a JavaScript environment, so use JSDoc for IntelliSense to introspect it.
      storySort: (a, b) =>
        a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }),
    },
  },
});
```

Asides from the unique story identifier, you can also use the `title`, `name`, and import path to sort your stories using the `storySort` function.

The `storySort` can also accept a configuration object.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    options: {
      storySort: {
        method: '',
        order: [],
        locales: '',
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    options: {
      storySort: {
        method: '',
        order: [],
        locales: '',
      },
    },
  },
});
```

| Field            | Type    | Description                                              | Required | Default Value           | Example                   |
| ---------------- | ------- | -------------------------------------------------------- | -------- | ----------------------- | ------------------------- |
| **method**       | String  | Tells Storybook in which order the stories are displayed | No       | Storybook configuration | `'alphabetical'`          |
| **order**        | Array   | The stories to be shown, ordered by supplied name        | No       | Empty Array `[]`        | `['Intro', 'Components']` |
| **includeNames** | Boolean | Include story name in sort calculation                   | No       | `false`                 | `true`                    |
| **locales**      | String  | The locale required to be displayed                      | No       | System locale           | `en-US`                   |

To sort your stories alphabetically, set `method` to `'alphabetical'` and optionally set the `locales` string. To sort your stories using a custom list, use the `order` array; stories that don't match an item in the `order` list will appear after the items in the list.

The `order` array can accept a nested array to sort 2nd-level story kinds. For example:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    options: {
      storySort: {
        order: ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components'],
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    options: {
      storySort: {
        order: ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components'],
      },
    },
  },
});
```

Which would result in this story ordering:

1. `Intro` and then `Intro/*` stories
2. `Pages` story
3. `Pages/Home` and `Pages/Home/*` stories
4. `Pages/Login` and `Pages/Login/*` stories
5. `Pages/Admin` and `Pages/Admin/*` stories
6. `Pages/*` stories
7. `Components` and `Components/*` stories
8. All other stories

If you want specific categories to sort to the end of the list, you can insert a `*` into your `order` array to indicate where "all other stories" should go:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    options: {
      storySort: {
        order: ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components', '*', 'WIP'],
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    options: {
      storySort: {
        order: ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components', '*', 'WIP'],
      },
    },
  },
});
```

In this example, the `WIP` category would be displayed at the end of the list.

Note that the `order` option is independent of the `method` option; stories are sorted first by the `order` array and then by either the `method: 'alphabetical'` or the default `configure()` import order.
> Source: https://storybook.js.org/docs/writing-stories/naming-components-and-hierarchy
---

# Mocking modules

Components often depend on other modules, such as other components, utility functions, or libraries. These can be from external packages or internal to your project. When rendering those components in Storybook or [testing](https://storybook.js.org/docs/writing-tests.md) them, you may want to mock those modules to control their behavior and isolate the component's functionality.

For example, this simple component depends on two modules, a local utility function to access the user's browser session and an external package to generate a unique ID:

```jsx title="AuthButton.jsx"

export function AuthButton() {
  const user = getUserFromSession();
  const id = uuidv4();

  return (
    <button
      onClick={() => {
        console.log(`User: ${user.name}, ID: ${id}`);
      }}
    >
      {user ? `Welcome, ${user.name}` : 'Sign in'}
    </button>
  );
}
```

The above example is written with React, but the same principles apply to other renderers like Vue, Svelte, or Web Components. The important part is the usage of the two module dependencies.

When writing stories or tests for this component, you may want to mock the `getUserFromSession` function to control the user data returned, or mock the `uuidv4` function to return a predictable ID. This allows you to test the component's behavior without relying on the actual implementations of these modules.

For maximum flexibility, Storybook provides three ways to mock modules for your stories. Let's walk through each of them, starting with the most straightforward approach.

## Automocking

Automocking is the most straightforward way to mock modules in Storybook, and we recommend it for all projects using the [Vite](https://storybook.js.org/docs/builders/vite.md) and [Webpack](https://storybook.js.org/docs/builders/webpack.md) builders (other builders must use one of the other techniques, below). This approach requires minimal configuration while allowing for flexible mocking of modules.

It works with two steps. First, register the modules you want to mock in your Storybook configuration. Then, control the behavior and make assertions about the mocked modules in your stories.

### Registering modules to mock

When automocking, you use the `sb.mock` utility function to register modules you want to mock. There are three ways to register modules: as spy-only, fully automocked, or with a mock file. Each method has its use cases and benefits.

There are some key details to keep in mind when using the `sb.mock` utility:

- You can register both local modules (e.g., `../lib/session.ts`) and packages in `node_modules` (e.g., `uuid`).
- You can only register mocked modules in your project-level configuration: `.storybook/preview.*`. This ensures consistent and performant mocking across all stories in your project. You can modify the behavior of these modules in your stories, but you cannot register them directly in the story files.
- When registering a mock for a local module, the path must:
  - Not use an alias or subpath import (e.g., `@/lib/session.ts` or `#lib/session`).
  - Be relative to the `.storybook/preview.*` file.
  - Include the file extension (e.g., `.ts` or `.js`).
- If you are using Typescript, you can wrap the module path in `import()` to ensure the module is correctly resolved and typed. For example, `sb.mock(import('../lib/session.ts'))`.
- If you are using the [Webpack builder](https://storybook.js.org/docs/builders/webpack.md), you can only automock `node_module` packages that have ESModules (ESM) entry points. If a module has both CommonJS (CJS) and ESM entry points, Webpack doesn't correctly resolve the ESM entry and it cannot be mocked. Webpack users can still mock CJS `node_module` packages by providing a [mock file](#mock-files).

#### Spy-only

For most cases, you should register a mocked module as spy-only, by setting the `spy` option to `true`. This leaves the original module's functionality intact, while still allowing you to modify the behavior if needed and make assertions in your tests.

For example, if you want to spy on the `getUserFromSession` function and the `uuidv4` function from the `uuid` package, you can call the `sb.mock` utility function in your `.storybook/preview.*` file:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, vue3-vite, sveltekit)

// 👇 Automatically spies on all exports from the `lib/session` local module
sb.mock(import('../lib/session.ts'), { spy: true });
// 👇 Automatically spies on all exports from the `uuid` package in `node_modules`
sb.mock(import('uuid'), { spy: true });

const preview: Preview = {
  // ...
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

// 👇 Automatically spies on all exports from the `lib/session` local module
sb.mock(import('../lib/session.ts'), { spy: true });
// 👇 Automatically spies on all exports from the `uuid` package in `node_modules`
sb.mock(import('uuid'), { spy: true });

export default definePreview({
  // ...
});
```

If you need to mock an external module that has a deeper import path (e.g. `lodash-es/add`), register the mock with that path.

You can then [control the behavior of these modules](#using-automocked-modules-in-stories) and make assertions about them in your stories, such as checking if a function was called or what arguments it was called with.

#### Fully automocked modules

For cases where you need to prevent the original module's functionality from executing, set the `spy` option to `false` (or omit it, because that is the default value). This will automatically replace all exports from the module with [Vitest mock functions](https://vitest.dev/api/mock.html), allowing you to control their behavior and make assertions while being certain that the original functionality never runs.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, vue3-vite, sveltekit)

// 👇 Automatically replaces all exports from the `lib/session` local module with mock functions
sb.mock(import('../lib/session.ts'));
// 👇 Automatically replaces all exports from the `uuid` package in `node_modules` with mock functions
sb.mock(import('uuid'));

const preview: Preview = {
  // ...
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

// 👇 Automatically replaces all exports from the `lib/session` local module with mock functions
sb.mock(import('../lib/session.ts'));
// 👇 Automatically replaces all exports from the `uuid` package in `node_modules` with mock functions
sb.mock(import('uuid'));

export default definePreview({
  // ...
});
```

Fully automocked modules do not execute their exported functions, but the module is still evaluated, along with its dependencies. This means that if the module has side effects (e.g., modifying global state, logging to the console, etc.), those side effects will still occur. Similarly, a module written to run on the server will attempt to be evaluated in the browser. If you want to prevent the original module's code from running entirely, you should use a [mock file](#mock-files) instead.

You can then [control the behavior of these modules](#using-automocked-modules-in-stories) and make assertions about them in your stories, just like with the spy-only approach.

#### Mock files

If you want to mock a module with more complex behavior or reuse a mock's behavior across multiple stories, you can create a mock file. This file should be placed in a `__mocks__` directory next to the module you want to mock, and it should export the same named exports as the original module.

For example, to mock the `session` module in the `lib` directory, create a file named `session.js|ts` in the `lib/__mocks__` directory:

```js title="lib/__mocks__/session.js"
export function getUserFromSession() {
  return { name: 'Mocked User' };
}
```

For packages in your `node_modules`, create a `__mocks__` directory in the root of your project and create the mock file there. For example, to mock the `uuid` package, create a file named `uuid.js` in the `__mocks__` directory:

```js title="__mocks__/uuid.js"
export function v4() {
  return '1234-5678-90ab-cdef';
}
```

If you need to mock an external module that has a deeper import path (e.g. `lodash-es/add`), create a corresponding mock file (e.g. `__mocks__/lodash-es/add.js`) in the root of your project.

The root of your project is determined differently depending on your builder:

**Vite projects**

The root `__mocks__` directory should be placed in the [`root` directory](https://vite.dev/config/shared-options.html#root), as defined in your project's Vite configuration (typically `process.cwd()`) If that is unavailable, it defaults to the directory containing your `.storybook` directory.

**Webpack projects**

The root `__mocks__` directory should be placed in the [`context` directory](https://webpack.js.org/configuration/entry-context/#context), as defined in your project's Webpack configuration (typically `process.cwd()`). If that is unavailable, it defaults to the root of your repository.

Mock files must be written with JavaScript (not TypeScript) using ESModules (not CJS).

They must export the same named exports as the original module. If you want to mock a default export, you can use `export default` in the mock file.

You can then use the `sb.mock` utility to register these mock files in your `preview.*` file:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, vue3-vite, sveltekit)

// 👇 Replaces imports of this module with imports to `../lib/__mocks__/session.ts`
sb.mock(import('../lib/session.ts'));
// 👇 Replaces imports of this module with imports to `../__mocks__/uuid.ts`
sb.mock(import('uuid'));

const preview: Preview = {
  // ...
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

// 👇 Replaces imports of this module with imports to `../lib/__mocks__/session.ts`
sb.mock(import('../lib/session.ts'));
// 👇 Replaces imports of this module with imports to `../__mocks__/uuid.ts`
sb.mock(import('uuid'));

export default definePreview({
  // ...
});
```

Note that the API for registering automatically mocked modules and mock files is the same. The only difference is that `sb.mock` will first look for a mock file in the appropriate directory before automatically mocking the module.

### Using automocked modules in stories

All registered automocked modules are used the same way within your stories. You can control the behavior, such as defining what it returns, and make assertions about the modules.

```ts
// AuthButton.stories.ts — CSF 3
// Replace your-framework with the name of your framework (e.g. react-vite, vue3-vite, etc.)

const meta = {
  component: AuthButton,
  // 👇 This will run before each story is rendered
  beforeEach: async () => {
    // 👇 Force known, consistent behavior for mocked modules
    mocked(uuidv4).mockReturnValue('1234-5678-90ab-cdef');
    mocked(getUserFromSession).mockReturnValue({ name: 'John Doe' });
  },
} satisfies Meta<typeof AuthButton>;
export default meta;

type Story = StoryObj<typeof meta>;

export const LogIn: Story = {
  play: async ({ canvas, userEvent }) => {
    const button = canvas.getByRole('button', { name: 'Sign in' });
    userEvent.click(button);

    // Assert that the getUserFromSession function was called
    expect(getUserFromSession).toHaveBeenCalled();
  },
};
```

```ts
// AuthButton.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: AuthButton,
  // 👇 This will run before each story is rendered
  beforeEach: async () => {
    // 👇 Force known, consistent behavior for mocked modules
    mocked(uuidv4).mockReturnValue('1234-5678-90ab-cdef');
    mocked(getUserFromSession).mockReturnValue({ name: 'John Doe' });
  },
});

export const LogIn = meta.story({
  play: async ({ canvas, userEvent }) => {
    const button = canvas.getByRole('button', { name: 'Sign in' });
    userEvent.click(button);

    // Assert that the getUserFromSession function was called
    expect(getUserFromSession).toHaveBeenCalled();
  },
});
```

Mocked functions created with the `sb.mock` utility are full [Vitest mock functions](https://vitest.dev/api/mock.html), which means you can use all the methods available on them. Some of the most useful methods include:

| Method                                                                           | Description                                           |
| -------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`mockReturnValue(value)`](https://vitest.dev/api/mock.html#mockreturnvalue)     | Sets the return value of the mocked function.         |
| [`mockResolvedValue(value)`](https://vitest.dev/api/mock.html#mockresolvedvalue) | Sets the value the mocked async function resolves to. |
| [`mockImplementation(fn)`](https://vitest.dev/api/mock.html#mockimplementation)  | Sets a custom implementation for the mocked function. |

If you are [writing your stories in TypeScript](https://storybook.js.org/docs/writing-stories/typescript.md), you can use the `mocked` utility from `storybook/test` to ensure that the mocked functions are correctly typed in your stories. This utility is a type-safe wrapper around the Vitest `vi.mocked` function.

### How it works

Storybook's automocking is built on Vitest's mocking engine. The behavior adjusts depending on whether you're in development mode or build mode:

**Dev Mode**

In dev mode, mocking relies on Vite's module graph invalidation. When a mock is added, changed, or removed (either in `.storybook/preview.*` or the `__mocks__` directory), the plugin intelligently invalidates all affected modules and triggers a hot reload. This provides a fast and interactive development experience.

**Dev and build mode**

- Build-time analysis: A new Vite plugin, viteMockPlugin, scans `.storybook/preview.*` for all `sb.mock()` calls during the build process.
- Mock Processing:
  - `__mocks__` redirects: If a corresponding file is found in the top-level `__mocks__` directory, that file is loaded and transformed by Vite.
  - Automocking & spies: If no `__mocks__` file is found, the original module's code is transformed at build-time to replace its exports with mocks or spies.
- No runtime overhead: Because all mocking decisions and transformations happen at build time, there is no performance penalty or complex interception logic needed in the final built application. The mocked modules are directly bundled in place of the originals.

#### Comparison to Vitest mocking

While this feature uses Vitest's mocking engine, the implementation within Storybook has some key differences:

- Scope: Mocks are global and defined only in `.storybook/preview.*`. Unlike Vitest, you cannot call `sb.mock()` inside individual story files.
- Static by Design: All mocking decisions are finalized at build time. This makes the system robust and performant but less dynamic than Vitest's test-by-test mocking capabilities. There is no `sb.unmock()` or equivalent, as the module graph is fixed in a production build.
- Runtime Mocking: While the module swap is static, you can still control the behavior of the mocked functions at runtime within a play function or `beforeEach` hook (e.g., `mocked(myFunction).mockReturnValue('new value')`).
- No Factory Functions: The `sb.mock()` API does not accept a factory function as its second argument (e.g., `sb.mock('path', () => ({...}))`). This is because all mocking decisions are resolved at build time, whereas factories are executed at runtime.

## Alternative methods

If [automocking](#automocking) is not suitable for your project, there are two alternative methods to mock modules in Storybook: [subpath imports](#subpath-imports) and [builder aliases](#builder-aliases). These methods require a bit more setup but provide similar functionality to automocking, allowing you to control the behavior of modules in your stories.

### Subpath imports

You can use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), a Node feature, to mock modules. Subpath imports allow you to define custom paths for modules in your project, which can be used to replace the original module with a mock file. They work with both the [Vite](https://storybook.js.org/docs/builders/vite.md) and [Webpack](https://storybook.js.org/docs/builders/webpack.md) builders.

#### Mock files

To mock a module, create a file with the same name and in the same directory as the module you want to mock. For example, to mock a module named `session`, create a file next to it named `session.mock.js|ts`, with a few characteristics:

- It must import the original module using a relative import.
  - Using a subpath or alias import would result in it importing itself.
- It should re-export all exports from the original module.
- It should use the `fn` utility to mock any necessary functionality from the original module.
- It should use the [`mockName`](https://vitest.dev/api/mock.html#mockname) method to ensure the name is preserved when minified
- It should not introduce side effects that could affect other tests or components. Mock files should be isolated and only affect the module they are mocking.

Here's an example of a mock file for a module named `session`:

```ts
// lib/session.mock.ts

export * from './session';
export const getUserFromSession = fn(actual.getUserFromSession).mockName('getUserFromSession');
```

When you use the `fn` utility to mock a module, you create full [Vitest mock functions](https://vitest.dev/api/mock.html). See [below](#using-mocked-modules-in-stories) for examples of how you can use a mocked module in your stories.

**Mock files for external modules**

You can't directly mock an external module like [`uuid`](https://github.com/uuidjs/uuid) or `node:fs`. Instead, you must wrap it in your own module, which you can mock like any other internal one. For example, with `uuid`, you could do the following:

```ts title="lib/uuid.ts"

export const uuidv4 = v4;
```

And create a mock for the wrapper:

```ts title="lib/uuid.mock.ts"

export const uuidv4 = fn(actual.uuidv4).mockName('uuidv4');
```

#### Configuration

To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for four internal modules:

```jsonc
// package.json
{
  "imports": {
    "#api": {
      // storybook condition applies to Storybook
      "storybook": "./api.mock.ts",
      "default": "./api.ts",
    },
    "#app/actions": {
      "storybook": "./app/actions.mock.ts",
      "default": "./app/actions.ts",
    },
    "#lib/session": {
      "storybook": "./lib/session.mock.ts",
      "default": "./lib/session.ts",
    },
    "#lib/db": {
      // test condition applies to test environments *and* Storybook
      "test": "./lib/db.mock.ts",
      "default": "./lib/db.ts",
    },
    "#*": ["./*", "./*.ts", "./*.tsx"],
  },
}
```

There are three aspects to this configuration worth noting:

First, **each subpath must begin with `#`**, to differentiate it from a regular module path. The `#*` entry is a catch-all that maps all subpaths to the root directory.

Second, the order of the keys is important. The `default` key should come last.

Third, note the **`storybook`, `test`, and `default` keys** in each module's entry. The `storybook` value is used to import the mock file when loaded in Storybook, while the `default` value is used to import the original module when loaded in your project. The `test` condition is also used within Storybook, which allows you to use the same configuration in Storybook and your other tests.

With the package configuration in place, you can then update your component file to use the subpath import:

```ts title="AuthButton.ts"
// ➖ Remove this line
// import { getUserFromSession } from '../../lib/session';
// ➕ Add this line

// ...rest of the file
```

Subpath imports will only be correctly resolved and typed when the [`moduleResolution` property](https://www.typescriptlang.org/tsconfig/#moduleResolution) is set to `'Bundler'`, `'NodeNext'`, or `'Node16'` in your TypeScript configuration.

If you are currently using `'node'`, that is intended for projects using a Node.js version older than v10. Projects written with modern code likely do not need to use `'node'`.

Storybook recommends the [TSConfig Cheat Sheet](https://www.totaltypescript.com/tsconfig-cheat-sheet) for guidance on setting up your TypeScript configuration.

#### Using subpath imports in stories

When you use the `fn` utility to mock a module, you create full [Vitest mock functions](https://vitest.dev/api/mock.html), which have many methods available. Some of the most useful methods include:

| Method                                                                           | Description                                           |
| -------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`mockReturnValue(value)`](https://vitest.dev/api/mock.html#mockreturnvalue)     | Sets the return value of the mocked function.         |
| [`mockResolvedValue(value)`](https://vitest.dev/api/mock.html#mockresolvedvalue) | Sets the value the mocked async function resolves to. |
| [`mockImplementation(fn)`](https://vitest.dev/api/mock.html#mockimplementation)  | Sets a custom implementation for the mocked function. |

Here, we define `beforeEach` on a story (which will run before the story is rendered) to set a mocked return value for the `getUserFromSession` function used by the Page component:

```ts
// Page.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// 👇 Automocked module resolves to '../lib/__mocks__/session'

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

export default meta;

type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  async beforeEach() {
    // 👇 Set the return value for the getUserFromSession function
    mocked(getUserFromSession).mockReturnValue({ id: '1', name: 'Alice' });
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

// 👇 Automocked module resolves to '../lib/__mocks__/session'

const meta = preview.meta({
  component: Page,
});

export const Basic = meta.story({
  async beforeEach() {
    // 👇 Set the return value for the getUserFromSession function
    mocked(getUserFromSession).mockReturnValue({ id: '1', name: 'Alice' });
  },
});
```

If you are [writing your stories in TypeScript](https://storybook.js.org/docs/writing-stories/typescript.md), you must import your mock modules using the full mocked file name to have the functions correctly typed in your stories. You do **not** need to do this in your component files. That's what the [subpath import](#subpath-imports) or [builder alias](#builder-aliases) is for.

#### Spying on mocked modules

The `fn` utility also spies on the original module's functions, which you can use to assert their behavior in your tests. For example, you can use [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md) to verify that a function was called with specific arguments.

For example, this story checks that the `saveNote` function was called when the user clicks the save button:

```ts
// NoteUI.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// 👇 Automocked module resolves to '../app/__mocks__/actions'

const meta = { component: NoteUI } satisfies Meta<typeof NoteUI>;
export default meta;

type Story = StoryObj<typeof meta>;

const notes = createNotes();

export const SaveFlow: Story = {
  name: 'Save Flow ▶',
  args: {
    isEditing: true,
    note: notes[0],
  },
  play: async ({ canvas, userEvent }) => {
    const saveButton = canvas.getByRole('menuitem', { name: /done/i });
    await userEvent.click(saveButton);
    // 👇 This is the mock function, so you can assert its behavior
    await expect(saveNote).toHaveBeenCalled();
  },
};
```

```ts
// NoteUI.stories.ts — CSF Next 🧪

// 👇 Automocked module resolves to '../app/__mocks__/actions'

const meta = preview.meta({ component: NoteUI });

const notes = createNotes();

export const SaveFlow = meta.story({
  name: 'Save Flow ▶',
  args: {
    isEditing: true,
    note: notes[0],
  },
  play: async ({ canvas, userEvent }) => {
    const saveButton = canvas.getByRole('menuitem', { name: /done/i });
    await userEvent.click(saveButton);
    // 👇 This is the mock function, so you can assert its behavior
    await expect(saveNote).toHaveBeenCalled();
  },
});
```

### Builder aliases

If your project is unable to use [automocking](#automocking) or [subpath imports](#subpath-imports), you can configure your Storybook builder to alias the module to the [mock file](#mock-files-1). This will instruct the builder to replace the module with the mock file when bundling your Storybook stories.

```ts
// .storybook/main.ts — Vite (CSF 3)
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs-vite, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  viteFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve?.alias,
        // 👇 External module
        lodash: import.meta.resolve('./lodash.mock'),
        // 👇 Internal modules
        '@/api': import.meta.resolve('./api.mock.ts'),
        '@/app/actions': import.meta.resolve('./app/actions.mock.ts'),
        '@/lib/session': import.meta.resolve('./lib/session.mock.ts'),
        '@/lib/db': import.meta.resolve('./lib/db.mock.ts'),
      };
    }

    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — Webpack (CSF 3)
// Replace your-framework with the framework you are using (e.g., nextjs, react-webpack5)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        // 👇 External module
        lodash: import.meta.resolve('./lodash.mock'),
        // 👇 Internal modules
        '@/api$': import.meta.resolve('./api.mock.ts'),
        '@/app/actions$': import.meta.resolve('./app/actions.mock.ts'),
        '@/lib/session$': import.meta.resolve('./lib/session.mock.ts'),
        '@/lib/db$': import.meta.resolve('./lib/db.mock.ts'),
      };
    }

    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — Vite (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  viteFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve?.alias,
        // 👇 External module
        lodash: import.meta.resolve('./lodash.mock'),
        // 👇 Internal modules
        '@/api': import.meta.resolve('./api.mock.ts'),
        '@/app/actions': import.meta.resolve('./app/actions.mock.ts'),
        '@/lib/session': import.meta.resolve('./lib/session.mock.ts'),
        '@/lib/db': import.meta.resolve('./lib/db.mock.ts'),
      };
    }

    return config;
  },
});
```

```ts
// .storybook/main.ts — Webpack (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., nextjs, react-webpack5)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        // 👇 External module
        lodash: import.meta.resolve('./lodash.mock'),
        // 👇 Internal modules
        '@/api$': import.meta.resolve('./api.mock.ts'),
        '@/app/actions$': import.meta.resolve('./app/actions.mock.ts'),
        '@/lib/session$': import.meta.resolve('./lib/session.mock.ts'),
        '@/lib/db$': import.meta.resolve('./lib/db.mock.ts'),
      };
    }

    return config;
  },
});
```

Usage of the aliased module in stories is similar to when [using subpath imports in stories](#using-subpath-imports-in-stories), but you import the module using the alias instead of the subpath.

---

## Common scenarios

### Setting up and cleaning up

Before the story renders, you can use the asynchronous `beforeEach` function to perform any setup you need (e.g., configure the mock behavior). This function can be defined at the story, component (which will run for all stories in the file), or project (defined in `.storybook/preview.*`, which will run for all stories in the project).

You can also return a cleanup function from `beforeEach` which will be called after your story unmounts. This is useful for tasks like unsubscribing observers, etc.

It is _not_ necessary to restore `fn()` mocks with the cleanup function, as Storybook will already do that automatically before rendering a story. See the [`parameters.test.restoreMocks` API](https://storybook.js.org/docs/api/parameters.md#restoremocks) for more information.

Here's an example of using the [`mockdate`](https://github.com/boblauer/MockDate) package to mock the [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) and reset it when the story unmounts.

```ts
// Page.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Page,
  // 👇 Set the value of Date for every story in the file
  async beforeEach() {
    MockDate.set('2024-02-14');

    // 👇 Reset the Date after each story
    return () => {
      MockDate.reset();
    };
  },
} satisfies Meta<typeof Page>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  async play({ canvas }) {
    // ... This will run with the mocked Date
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Page,
  // 👇 Set the value of Date for every story in the file
  async beforeEach() {
    MockDate.set('2024-02-14');

    // 👇 Reset the Date after each story
    return () => {
      MockDate.reset();
    };
  },
});

export const Basic = meta.story({
  async play({ canvas }) {
    // ... This will run with the mocked Date
  },
});
```

---

## Troubleshooting

### Receiving an `exports is not defined` error

Webpack projects may encounter an `exports is not defined` error when using [automocking](#automocking). This is usually caused by attempting to mock a module with CommonJS (CJS) entry points. Automocking with Webpack only works with modules that have ESModules (ESM) entry points exclusively, so you must use a [mock file](#mock-files) to mock CJS modules.

### Mocking conflicts with other testing tools

If you've already set up mocking with other testing tools (e.g., [Jest](https://jestjs.io/)), you may encounter conflicts when using Storybook's mocking system. These conflicts can cause unexpected behavior, errors, or incorrect mocks when both tools try to mock the same module. This is a known issue when sharing mock files or configurations between Storybook and other testing tools. To address this situation, we recommend that you verify which tool is responsible for mocking a particular module and make sure the configurations do not overlap to avoid any conflicts.
> Source: https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules
---

# Mocking network requests

For components that make network requests (e.g. fetching data from a REST or GraphQL API), you can mock those requests using a tool like [Mock Service Worker (MSW)](https://mswjs.io/). MSW is an API mocking library, which relies on service workers to capture network requests and provides mocked data in response.

The [MSW addon](https://storybook.js.org/addons/msw-storybook-addon/) brings this functionality into Storybook, allowing you to mock API requests in your stories. Below is an overview of how to set up and use the addon.

## Set up the MSW addon

First, if necessary, run this command to install MSW and the MSW addon:

```sh
npm install msw msw-storybook-addon --save-dev
```

```sh
pnpm add msw msw-storybook-addon --save-dev
```

```sh
yarn add msw msw-storybook-addon --save-dev
```

If you're not already using MSW, generate the service worker file necessary for MSW to work:

```shell
npx msw init public/
```

```shell
yarn dlx msw init public/
```

```shell
pnpm dlx msw init public/
```

Then ensure the [`staticDirs`](https://storybook.js.org/docs/api/main-config/main-config-static-dirs.md) property in your Storybook configuration will include the generated service worker file (in `/public`, by default):

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
});
```

Finally, initialize the addon and apply it to all stories with a [project-level loader](https://storybook.js.org/docs/writing-stories/loaders.md#global-loaders):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

/*
 * Initializes MSW
 * See https://github.com/mswjs/msw-storybook-addon#configuring-msw
 * to learn how to customize it
 */
initialize();

const preview: Preview = {
  loaders: [mswLoader], // 👈 Add the MSW loader to all stories
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

/*
 * Initializes MSW
 * See https://github.com/mswjs/msw-storybook-addon#configuring-msw
 * to learn how to customize it
 */
initialize();

export default definePreview({
  loaders: [mswLoader], // 👈 Add the MSW loader to all stories
});
```

## Mocking REST requests

If your component fetches data from a REST API, you can use MSW to mock those requests in Storybook. As an example, consider this document screen component:

```ts
// YourPage.tsx

// Example hook to retrieve data from an external endpoint
function useFetchData() {
  const [status, setStatus] = useState<string>('idle');
  const [data, setData] = useState<any[]>([]);
  useEffect(() => {
    setStatus('loading');
    fetch('https://your-restful-endpoint')
      .then((res) => {
        if (!res.ok) {
          throw new Error(res.statusText);
        }
        return res;
      })
      .then((res) => res.json())
      .then((data) => {
        setStatus('success');
        setData(data);
      })
      .catch(() => {
        setStatus('error');
      });
  }, []);

  return {
    status,
    data,
  };
}

export function DocumentScreen() {
  const { status, data } = useFetchData();

  const { user, document, subdocuments } = data;

  if (status === 'loading') {
    return <p>Loading...</p>;
  }
  if (status === 'error') {
    return <p>There was an error fetching the data!</p>;
  }
  return (
    
      
      
    
  );
}
```

This example uses the [`fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/fetch) to make network requests. If you're using a different library (e.g. [`axios`](https://axios-http.com/)), you can apply the same principles to mock network requests in Storybook.

With the MSW addon, we can write stories that use MSW to mock the REST requests. Here's an example of two stories for the document screen component: one that fetches data successfully and another that fails.

```ts
// YourPage.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

// 👇 The mocked data that will be used in the story
const TestData = {
  user: {
    userID: 1,
    name: 'Someone',
  },
  document: {
    id: 1,
    userID: 1,
    title: 'Something',
    brief: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
    status: 'approved',
  },
  subdocuments: [
    {
      id: 1,
      userID: 1,
      title: 'Something',
      content:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
      status: 'approved',
    },
  ],
};

export const MockedSuccess: Story = {
  parameters: {
    msw: {
      handlers: [
        http.get('https://your-restful-endpoint/', () => {
          return HttpResponse.json(TestData);
        }),
      ],
    },
  },
};

export const MockedError: Story = {
  parameters: {
    msw: {
      handlers: [
        http.get('https://your-restful-endpoint', async () => {
          await delay(800);
          return new HttpResponse(null, {
            status: 403,
          });
        }),
      ],
    },
  },
};
```

```ts
// YourPage.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: DocumentScreen,
});

// 👇 The mocked data that will be used in the story
const TestData = {
  user: {
    userID: 1,
    name: 'Someone',
  },
  document: {
    id: 1,
    userID: 1,
    title: 'Something',
    brief: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
    status: 'approved',
  },
  subdocuments: [
    {
      id: 1,
      userID: 1,
      title: 'Something',
      content:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
      status: 'approved',
    },
  ],
};

export const MockedSuccess = meta.story({
  parameters: {
    msw: {
      handlers: [
        http.get('https://your-restful-endpoint/', () => {
          return HttpResponse.json(TestData);
        }),
      ],
    },
  },
});

export const MockedError = meta.story({
  parameters: {
    msw: {
      handlers: [
        http.get('https://your-restful-endpoint', async () => {
          await delay(800);
          return new HttpResponse(null, {
            status: 403,
          });
        }),
      ],
    },
  },
});
```

## Mocking GraphQL requests

GraphQL is another common way to fetch data in components. You can use MSW to mock GraphQL requests in Storybook. Here's an example of a document screen component that fetches data from a GraphQL API:

```ts
// YourPage.tsx

const AllInfoQuery = gql`
  query AllInfo {
    user {
      userID
      name
    }
    document {
      id
      userID
      title
      brief
      status
    }
    subdocuments {
      id
      userID
      title
      content
      status
    }
  }
`;

interface Data {
  allInfo: {
    user: {
      userID: number;
      name: string;
      opening_crawl: boolean;
    };
    document: {
      id: number;
      userID: number;
      title: string;
      brief: string;
      status: string;
    };
    subdocuments: {
      id: number;
      userID: number;
      title: string;
      content: string;
      status: string;
    };
  };
}

function useFetchInfo() {
  const { loading, error, data } = useQuery<Data>(AllInfoQuery);

  return { loading, error, data };
}

export function DocumentScreen() {
  const { loading, error, data } = useFetchInfo();

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>There was an error fetching the data!</p>;
  }

  return (
    
      
      
    
  );
}
```

This example uses GraphQL with [Apollo Client](https://www.apollographql.com/docs/) to make network requests. If you're using a different library (e.g. [URQL](https://formidable.com/open-source/urql/) or [React Query](https://react-query.tanstack.com/)), you can apply the same principles to mock network requests in Storybook.

The MSW addon allows you to write stories that use MSW to mock the GraphQL requests. Here's an example demonstrating two stories for the document screen component. The first story fetches data successfully, while the second story fails.

```tsx
// YourPage.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const mockedClient = new ApolloClient({
  uri: 'https://your-graphql-endpoint',
  cache: new InMemoryCache(),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'no-cache',
      errorPolicy: 'all',
    },
    query: {
      fetchPolicy: 'no-cache',
      errorPolicy: 'all',
    },
  },
});

//👇The mocked data that will be used in the story
const TestData = {
  user: {
    userID: 1,
    name: 'Someone',
  },
  document: {
    id: 1,
    userID: 1,
    title: 'Something',
    brief: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
    status: 'approved',
  },
  subdocuments: [
    {
      id: 1,
      userID: 1,
      title: 'Something',
      content:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
      status: 'approved',
    },
  ],
};
const meta = {
  component: DocumentScreen,
  decorators: [
    (Story) => (
      
        
      
    ),
  ],
} satisfies Meta<typeof DocumentScreen>;

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

export const MockedSuccess: Story = {
  parameters: {
    msw: {
      handlers: [
        graphql.query('AllInfoQuery', () => {
          return HttpResponse.json({
            data: {
              allInfo: {
                ...TestData,
              },
            },
          });
        }),
      ],
    },
  },
};

export const MockedError: Story = {
  parameters: {
    msw: {
      handlers: [
        graphql.query('AllInfoQuery', async () => {
          await delay(800);
          return HttpResponse.json({
            errors: [
              {
                message: 'Access denied',
              },
            ],
          });
        }),
      ],
    },
  },
};
```

```tsx
// YourPage.stories.ts|tsx — CSF Next 🧪

const mockedClient = new ApolloClient({
  uri: 'https://your-graphql-endpoint',
  cache: new InMemoryCache(),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'no-cache',
      errorPolicy: 'all',
    },
    query: {
      fetchPolicy: 'no-cache',
      errorPolicy: 'all',
    },
  },
});

//👇The mocked data that will be used in the story
const TestData = {
  user: {
    userID: 1,
    name: 'Someone',
  },
  document: {
    id: 1,
    userID: 1,
    title: 'Something',
    brief: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
    status: 'approved',
  },
  subdocuments: [
    {
      id: 1,
      userID: 1,
      title: 'Something',
      content:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
      status: 'approved',
    },
  ],
};
const meta = preview.meta({
  component: DocumentScreen,
  decorators: [
    (Story) => (
      
        
      
    ),
  ],
});

export const MockedSuccess = meta.story({
  parameters: {
    msw: {
      handlers: [
        graphql.query('AllInfoQuery', () => {
          return HttpResponse.json({
            data: {
              allInfo: {
                ...TestData,
              },
            },
          });
        }),
      ],
    },
  },
});

export const MockedError = meta.story({
  parameters: {
    msw: {
      handlers: [
        graphql.query('AllInfoQuery', async () => {
          await delay(800);
          return HttpResponse.json({
            errors: [
              {
                message: 'Access denied',
              },
            ],
          });
        }),
      ],
    },
  },
});
```

## Configuring MSW for stories

In the examples above, note how each story is configured with `parameters.msw` to define the request handlers for the mock server. Because it uses parameters in this way, it can also be configured at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) or even [project](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) level, allowing you to share the same mock server configuration across multiple stories.
> Source: https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-network-requests
---

# Mocking providers

The [context provider pattern](https://react.dev/learn/passing-data-deeply-with-context) and how to mock it only applies to renderers that use JSX, like [React](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/?renderer=react.md) or [Solid](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/?renderer=solid.md).

Components can receive data or configuration from context providers. For example, a styled component might access its theme from a ThemeProvider or Redux uses React context to provide components access to app data. To mock a provider, you can wrap your component in a [decorator](https://storybook.js.org/docs/writing-stories/decorators.md) that includes the necessary context.

```tsx
// .storybook/preview.tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const preview: Preview = {
  decorators: [
    (Story) => (
      
        
        
      
    ),
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [
    (Story) => (
      
        
        
      
    ),
  ],
});
```

Note the file extension above (`.tsx` or `.jsx`). You may need to adjust your preview file's extension to allow use of JSX, depending on your project's settings.

For another example, reference the [Screens](https://storybook.js.org/tutorials/intro-to-storybook/react/en/screen/) chapter of the Intro to Storybook tutorial, where we mock a Redux provider with mock data.

## Configuring the mock provider

When mocking a provider, it may be necessary to configure the provider to supply a different value for individual stories. For example, you might want to test a component with different themes or user roles.

One way to do this is to define the decorator for each story individually. But if you imagine a scenario where you wish to create stories for each of your components in both light and dark themes, this approach can quickly become cumbersome.

For a better way, with much less repetition, you can use the [decorator function's second "context" argument](https://storybook.js.org/docs/writing-stories/decorators.md#context-for-mocking) to access a story's [`parameters`](https://storybook.js.org/docs/writing-stories/parameters.md) and adjust the provided value. This way, you can define the provider once and adjust its value for each story.

For example, we can adjust the decorator from above to read from `parameters.theme` to determine which theme to provide:

```tsx
// .storybook/preview.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// themes = { light, dark }

const preview: Preview = {
  decorators: [
    // 👇 Defining the decorator in the preview file applies it to all stories
    (Story, { parameters }) => {
      // 👇 Make it configurable by reading the theme value from parameters
      const { theme = 'light' } = parameters;
      return (
        
          
        
      );
    },
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

// themes = { light, dark }

export default definePreview({
  decorators: [
    // 👇 Defining the decorator in the preview file applies it to all stories
    (Story, { parameters }) => {
      // 👇 Make it configurable by reading the theme value from parameters
      const { theme = 'light' } = parameters;
      return (
        
          
        
      );
    },
  ],
});
```

Now, you can define a `theme` parameter in your stories to adjust the theme provided by the decorator:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

type Story = StoryObj<typeof meta>;

// Wrapped in light theme
export const Basic: Story = {};

// Wrapped in dark theme
export const Dark: Story = {
  parameters: {
    theme: 'dark',
  },
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

// Wrapped in light theme
export const Basic = meta.story();

// Wrapped in dark theme
export const Dark = meta.story({
  parameters: {
    theme: 'dark',
  },
});
```

This powerful approach allows you to provide any value (theme, user role, mock data, etc.) to your components in a way that is both flexible and maintainable.
> Source: https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-providers
---

# Building pages with Storybook

Storybook helps you build any component, from small “atomic” components to composed pages. But as you move up the component hierarchy toward the page level, you deal with more complexity.

There are many ways to build pages in Storybook. Here are common patterns and solutions.

- Pure presentational pages.
- Connected components (e.g., network requests, context, browser environment).

## Pure presentational pages

Teams at the BBC, The Guardian, and the Storybook maintainers themselves build pure presentational pages. If you take this approach, you don't need to do anything special to render your pages in Storybook.

It's straightforward to write components to be fully presentational up to the screen level. That makes it easy to show in Storybook. The idea is that you do all the messy “connected” logic in a single wrapper component in your app outside of Storybook. You can see an example of this approach in the [Data](https://storybook.js.org/tutorials/intro-to-storybook/react/en/data/) chapter of the Intro to Storybook tutorial.

The benefits:

- Easy to write stories once components are in this form.
- All the data for the story is encoded in the args of the story, which works well with other parts of Storybook's tooling (e.g. [controls](https://storybook.js.org/docs/essentials/controls.md)).

The downsides:

- Your existing app may not be structured in this way, and it may be difficult to change it.

- Fetching data in one place means that you need to drill it down to the components that use it. This can be natural in a page that composes one big GraphQL query (for instance), but other data fetching approaches may make this less appropriate.

- It's less flexible if you want to load data incrementally in different places on the screen.

### Args composition for presentational screens

When you are building screens in this way, it is typical that the inputs of a composite component are a combination of the inputs of the various sub-components it renders. For instance, if your screen renders a page layout (containing details of the current user), a header (describing the document you are looking at), and a list (of the subdocuments), the inputs of the screen may consist of the user, document and subdocuments.

```tsx
// YourPage.ts|tsx

export interface DocumentScreenProps {
  user?: {};
  document?: Document;
  subdocuments?: SubDocuments[];
}

export function DocumentScreen({ user, document, subdocuments }: DocumentScreenProps) {
  return (
    
      
      
    
  );
}
```

In such cases, it is natural to use [args composition](https://storybook.js.org/docs/writing-stories/args.md#args-composition) to build the stories for the page based on the stories of the sub-components:

```ts
// YourPage.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// 👇 Imports the required stories

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

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

export const Simple: Story = {
  args: {
    user: PageLayout.Simple.args.user,
    document: DocumentHeader.Simple.args.document,
    subdocuments: DocumentList.Simple.args.documents,
  },
};
```

```ts
// YourPage.stories.ts|tsx — CSF Next 🧪

// 👇 Imports the required stories

const meta = preview.meta({
  component: DocumentScreen,
});

export const Simple = meta.story({
  args: {
    user: PageLayout.Simple.input.args.user,
    document: DocumentHeader.Simple.input.args.document,
    subdocuments: DocumentList.Simple.input.args.documents,
  },
});
```

This approach is beneficial when the various subcomponents export a complex list of different stories. You can pick and choose to build realistic scenarios for your screen-level stories without repeating yourself. Your story maintenance burden is minimal by reusing the data and taking a Don't-Repeat-Yourself(DRY) philosophy.

## Mocking connected components

Connected components are components that depend on external data or services. For example, a full page component is often a connected component. When you render a connected component in Storybook, you need to mock the data or modules that the component depends on. There are various layers in which you can do that.

### [Mocking imports](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md)

Components can depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to mock those modules to control their behavior.

### [Mocking API Services](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-network-requests.md)

For components that make network requests (e.g., fetching data from a REST or GraphQL API), you can mock those requests in your stories.

### [Mocking providers](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-providers.md)

Components can receive data or configuration from context providers. For example, a styled component might access its theme from a ThemeProvider or Redux uses React context to provide components access to app data. You can mock a provider and the value it's providing and wrap your component with it in your stories.

### Avoiding mocking dependencies

It's possible to avoid mocking the dependencies of connected "container" components entirely by passing them around via props or React context. However, it requires a strict split of the container and presentational component logic. For example, if you have a component responsible for data fetching logic and rendering DOM, it will need to be mocked as previously described.

It’s common to import and embed container components amongst presentational components. However, as we discovered earlier, we’ll likely have to mock their dependencies or the imports to render them within Storybook.

Not only can this quickly grow to become a tedious task, but it’s also challenging to mock container components that use local states. So, instead of importing containers directly, a solution to this problem is to create a React context that provides the container components. It allows you to freely embed container components as usual, at any level in the component hierarchy without worrying about subsequently mocking their dependencies; since we can swap out the containers themselves with their mocked presentational counterpart.

We recommend dividing context containers up over specific pages or views in your app. For example, if you had a `ProfilePage` component, you might set up a file structure as follows:

```
ProfilePage.js
ProfilePage.stories.js
ProfilePageContainer.js
ProfilePageContext.js
```

It’s also often helpful to set up a “global” container context (perhaps named `GlobalContainerContext`) for container components that may be rendered on every page of your app and add them to the top level of your application. While it’s possible to place every container within this global context, it should only provide globally required containers.

Let’s look at an example implementation of this approach.

First, create a React context, and name it `ProfilePageContext`. It does nothing more than export a React context:

```js
// ProfilePageContext.js|jsx

const ProfilePageContext = createContext();

export default ProfilePageContext;
```

`ProfilePage` is our presentational component. It will use the `useContext` hook to retrieve the container components from `ProfilePageContext`:

```js
// ProfilePage.js|jsx

export const ProfilePage = ({ name, userId }) => {
  const { UserPostsContainer, UserFriendsContainer } = useContext(ProfilePageContext);

  return (
    <div>
      <h1>{name}</h1>
      
      
    </div>
  );
};
```

#### Mocking containers in Storybook

In the context of Storybook, instead of providing container components through context, we’ll instead provide their mocked counterparts. In most cases, the mocked versions of these components can often be borrowed directly from their associated stories.

```js
// ProfilePage.stories.js|jsx

//👇 Imports a specific story from a story file

export default {
  component: ProfilePage,
};

const ProfilePageProps = {
  name: 'Jimi Hendrix',
  userId: '1',
};

const context = {
  //👇 We can access the `userId` prop here if required:
  UserPostsContainer({ userId }) {
    return ;
  },
  // Most of the time we can simply pass in a story.
  // In this case we're passing in the `normal` story export
  // from the `UserFriends` component stories.
  UserFriendsContainer: UserFriendsNormal,
};

export const Normal = {
  render: () => (
    <ProfilePageContext.Provider value={context}>
      
    </ProfilePageContext.Provider>
  ),
};
```

If the same context applies to all `ProfilePage` stories, we can use a [decorator](https://storybook.js.org/docs/writing-stories/decorators.md).

#### Providing containers to your application

Now, in the context of your application, you’ll need to provide `ProfilePage` with all of the container components it requires by wrapping it with `ProfilePageContext.Provider`:

For example, in Next.js, this would be your `pages/profile.js` component.

```js
// pages/profile.js|jsx

//👇 Ensure that your context value remains referentially equal between each render.
const context = {
  UserPostsContainer,
  UserFriendsContainer,
};

export const AppProfilePage = () => {
  return (
    <ProfilePageContext.Provider value={context}>
      
    </ProfilePageContext.Provider>
  );
};
```

#### Mocking global containers in Storybook

If you’ve set up `GlobalContainerContext`, you’ll need to set up a decorator within Storybook’s `preview.js` to provide context to all stories. For example:

```tsx
// .storybook/preview.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const context = {
  NavigationContainer: NavigationNormal,
};

const AppDecorator = (storyFn) => {
  return (
    <GlobalContainerContext.Provider value={context}>{storyFn()}</GlobalContainerContext.Provider>
  );
};

const preview: Preview = {
  decorators: [AppDecorator],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const context = {
  NavigationContainer: NavigationNormal,
};

const AppDecorator = (storyFn) => {
  return (
    <GlobalContainerContext.Provider value={context}>{storyFn()}</GlobalContainerContext.Provider>
  );
};

export default definePreview({
  decorators: [AppDecorator],
});
```
> Source: https://storybook.js.org/docs/writing-stories/build-pages-with-storybook
---

# Stories for multiple components

It's useful to write stories that [render two or more components](https://storybook.js.org/docs/writing-stories/index.md#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroup`, `List`, and `Page` components.

## Subcomponents

When the components you're documenting have a parent-child relationship, you can use the `subcomponents` property to document them together. This is especially useful when the child component is not meant to be used on its own, but only as part of the parent component.

Here's an example with `List` and `ListItem` components:

```tsx
// List.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: List,
  subcomponents: { ListItem }, //👈 Adds the ListItem component as a subcomponent
} satisfies Meta<typeof List>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Empty: Story = {};

export const OneItem: Story = {
  render: (args) => (
    
      
    
  ),
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: List,
  subcomponents: { ListItem }, //👈 Adds the ListItem component as a subcomponent
});

export const Empty = meta.story();

export const OneItem = meta.story({
  render: (args) => (
    
      
    
  ),
});
```

Note that by adding a `subcomponents` property to the meta (or default export), we get an extra panel on the [ArgTypes](https://storybook.js.org/docs/writing-docs/doc-blocks.md#argtypes) and [Controls](https://storybook.js.org/docs/essentials/controls.md) tables, listing the props of `ListItem`:

![Subcomponents in ArgTypes doc block](../_assets/writing-stories/doc-block-arg-types-subcomponents-for-list.png)

Subcomponents are only intended for documentation purposes and have some limitations:

1. The [argTypes](https://storybook.js.org/docs/api/arg-types.md) of subcomponents are [inferred (for the renderers that support that feature)](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference) and cannot be manually defined or overridden.
2. The table for each documented subcomponent does _not_ include [controls](https://storybook.js.org/docs/essentials/controls.md) to change the value of the props, because controls always apply to the main component's args.

Let's talk about some techniques you can use to mitigate the above, which are especially useful in more complicated situations.

## Reusing story definitions

We can also reduce repetition in our stories by reusing story definitions. Here, we can reuse the `ListItem` stories' args in the story for `List`:

```tsx
// List.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 We're importing the necessary stories from ListItem

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

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

export const ManyItems: Story = {
  render: (args) => (
    
      
      
      
    
  ),
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

//👇 We're importing the necessary stories from ListItem

const meta = preview.meta({
  component: List,
});

export const ManyItems = meta.story({
  render: (args) => (
    
      
      
      
    
  ),
});
```

By rendering the `Unchecked` story with its args, we are able to reuse the input data from the `ListItem` stories in the `List`.

However, we still aren’t using args to control the `ListItem` stories, which means we cannot change them with controls and we cannot reuse them in other, more complex component stories.

## Using children as an arg

One way we improve that situation is by pulling the rendered subcomponent out into a `children` arg:

```tsx
// List.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 Instead of importing ListItem, we import the stories

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

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

export const OneItem: Story = {
  args: {
    children: ,
  },
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

//👇 Instead of importing ListItem, we import the stories

const meta = preview.meta({
  component: List,
});

export const OneItem = meta.story({
  args: {
    children: ,
  },
});
```

Now that `children` is an arg, we can potentially reuse it in another story.

However, there are some caveats when using this approach that you should be aware of.

The `children` arg, just like all args, needs to be JSON serializable. To avoid errors with your Storybook, you should:

- Avoid using empty values
- Use [mapping](https://storybook.js.org/docs/essentials/controls.md#dealing-with-complex-values) if you want to adjust the value with [controls](https://storybook.js.org/docs/essentials/controls.md)
- Use caution with components that include third party libraries

We're currently working on improving the overall experience for the children arg and allow you to edit children arg in a control and allow you to use other types of components in the near future. But for now you need to factor in this caveat when you're implementing your stories.

## Creating a Template Component

Another option that is more “data”-based is to create a special “story-generating” template component:

```tsx
// List.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 Imports a specific story from ListItem stories

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

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

//👇 The ListTemplate construct will be spread to the existing stories.
const ListTemplate: Story = {
  render: ({ items, ...args }) => {
    return (
      
        {items.map((item) => (
          
        ))}
      
    );
  },
};

export const Empty = {
  ...ListTemplate,
  args: {
    items: [],
  },
};

export const OneItem = {
  ...ListTemplate,
  args: {
    items: [{ ...Unchecked.args }],
  },
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

//👇 Imports a specific story from ListItem stories

const meta = preview.meta({
  component: List,
});

export const Empty = meta.story({
  render: ({ items, ...args }) => {
    return (
      
        {items.map((item) => (
          
        ))}
      
    );
  },
  args: {
    items: [],
  },
});

export const OneItem = Empty.extend({
  args: {
    items: [{ ...Unchecked.input.args }],
  },
});
```

This approach requires more setup, but it means you can reuse the `args` to each story in a composite component. It also means you can alter the args to the component with the [Controls panel](https://storybook.js.org/docs/essentials/controls.md).
> Source: https://storybook.js.org/docs/writing-stories/stories-for-multiple-components
---

# Writing stories in TypeScript

Writing your stories in [TypeScript](https://www.typescriptlang.org/) makes you more productive. You don't have to jump between files to look up component props. Your code editor will alert you about missing required props and even autocomplete prop values, just like when using your components within your app. Plus, Storybook infers those component types to auto-generate the [Controls](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md) table.

Storybook has built-in TypeScript support, so you can get started with zero configuration required.

[CSF Next](https://storybook.js.org/docs/api/csf/csf-next.md) (currently in preview) provides significantly improved TypeScript support, which infers component types automatically and requires no explicit typing for most cases. We recommend using CSF Next for all new TypeScript stories.

You only need to add types when using [custom args](#typing-custom-args).

## Typing stories with `Meta` and `StoryObj`

When writing stories, there are two aspects that are helpful to type. The first is the [component meta](https://storybook.js.org/docs/writing-stories/index.md#default-export), which describes and configures the component and its stories. In a [CSF file](https://storybook.js.org/docs/api/csf.md), this is the default export. The second is the [stories themselves](https://storybook.js.org/docs/writing-stories/index.md#defining-stories).

Storybook provides utility types for each of these, named `Meta` and `StoryObj`. Here's an example CSF file using those types:

```ts
// Button.stories.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

type Story = StoryObj<typeof meta>;

export const Basic = {} satisfies Story;

export const Primary = {
  args: {
    primary: true,
  },
} satisfies Story;
```

### Props type parameter

`Meta` and `StoryObj` types are both [generics](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables), so you can provide them with an optional prop type parameter for the component type or the component's props type (e.g., the `typeof Button` portion of `Meta<typeof Button>`). By doing so, TypeScript will prevent you from defining an invalid arg, and all [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [play functions](https://storybook.js.org/docs/writing-stories/play-function.md), or [loaders](https://storybook.js.org/docs/writing-stories/loaders.md) will type their function arguments.

The example above passes a component type. See [**Typing custom args**](#typing-custom-args) for an example of passing a props type.

### Using `satisfies` for better type safety

  

    We are not yet able to provide additional type safety using the `satisfies` operator with Angular and Web components.

    <details>
      <summary>More info</summary>

      Both Angular and Web components utilize a class plus decorator approach. The decorators provide runtime metadata, but do not offer metadata at compile time.

      As a result, it appears impossible to determine if a property in the class is a required property or an optional property (but non-nullable due to a default value) or a non-nullable internal state variable.

      For more information, please refer to [this discussion](https://github.com/storybookjs/storybook/discussions/20988).

    </details>

  

If you are using TypeScript 4.9+, you can take advantage of the new [`satisfies`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html) operator to get stricter type checking. Now you will receive type errors for missing required args, not just invalid ones.

Using `satisfies` to apply a story's type helps maintain type safety when sharing a [play function](https://storybook.js.org/docs/writing-stories/play-function.md) across stories. Without it, TypeScript will throw an error that the `play` function may be undefined. The `satisfies` operator enables TypeScript to infer whether the play function is defined or not.

Finally, use of `satisfies` allows you to pass `typeof meta` to the `StoryObj` generic. This informs TypeScript of the connection between the `meta` and `StoryObj` types, which allows it to infer the `args` type from the `meta` type. In other words, TypeScript will understand that args can be defined both at the story and meta level and won't throw an error when a required arg is defined at the meta level, but not at the story level.

## Typing custom args

Sometimes stories need to define args that aren’t included in the component's props. For this case, you can use an [intersection type](https://www.typescriptlang.org/docs/handbook/2/objects.html#intersection-types) to combine a component's props type and your custom args' type. For example, here's how you could use a `footer` arg to populate a child component:

```tsx
// Page.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & { footer?: string };

const meta = {
  component: Page,
  render: ({ footer, ...args }) => (
    
      <footer>{footer}</footer>
    
  ),
} satisfies Meta;
export default meta;

type Story = StoryObj<typeof meta>;

export const CustomFooter = {
  args: {
    footer: 'Built with Storybook',
  },
} satisfies Story;
```

```tsx
// Page.stories.ts|tsx — CSF Next 🧪

type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & {
  footer?: string;
};

const meta = preview.type<{ args: PagePropsAndCustomArgs }>().meta({
  component: Page,
  render: ({ footer, ...args }) => (
    <Page {...args}>
      <footer>{footer}</footer>
    
  ),
});

export const CustomFooter = meta.story({
  args: {
    footer: 'Built with Storybook',
  },
});
```
> Source: https://storybook.js.org/docs/writing-stories/typescript
---

# How to test UIs with Storybook

Storybook [stories](https://storybook.js.org/docs/writing-stories.md) are test cases for your UI components in their various states and configurations. With Storybook, you can develop and test your components at the same time, in multiple ways, with instant feedback.

Storybook tackles UI component testing from a holistic perspective, ensuring that you can not only execute component tests quickly and reliably, but that you also have well-established patterns to develop, debug, maintain, and even collaborate on these tests across the development lifecycle.

## Get started

If your project is using Vite, you can likely use the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) to run your component tests in Storybook. This addon is built on top of [Vitest](https://vitest.dev/), a fast and lightweight test runner that works seamlessly with Vite.

Run this command, which will install and configure the Vitest addon and Vitest:

```shell
npx storybook add @storybook/addon-vitest
```

```shell
pnpm exec storybook add @storybook/addon-vitest
```

```shell
yarn exec storybook add @storybook/addon-vitest
```

The full installation instructions, including project requirements, are available in the [Vitest addon documentation](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#install-and-set-up).

Once your project is set up, you will see a testing widget in the bottom of your sidebar. After running tests, you will also see test status indicators on sidebar items. Additionally, many tests can be debugged with an addon panel.

![Storybook app with story status indicators, testing widget, and interactions panel annotated](../_assets/writing-tests/testing-ui-overview.png)

If you cannot use the Vitest addon in your project, you can still run tests using the [test-runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md).

Next, we’ll cover some key concepts of testing in Storybook.

## Key concepts

Testing in Storybook is similar to other testing environments. Most of the knowledge and techniques you’ve been using apply here, too. But there are also some significant improvements.

### Component tests

A component test is a test which:

- Renders a component in the browser for high fidelity
- Simulates a user interacting with actual UI, like an end-to-end (E2E) test
- Only tests a unit (e.g. a single component) of UI, **and** can reach into the implementation to mock things or manipulate data, like a unit test

This combination of using a real browser, simulating behavior, and mocking provides a powerful means of testing the functional aspects of your UI.

In Storybook, the entire testing experience is built around component tests. This means that you can run your tests in the same environment as your stories, with the same tools and techniques.

### Storybook Test

Storybook Test enables real-time testing of your stories, through the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md). It uses a Vitest plugin to automatically transform your stories into real Vitest tests, which are then run with Vitest’s browser mode.

### Watch mode

Get instant test feedback as you develop with watch mode. It will watch your code—either the component source or the tests—for changes and automatically re-run only the relevant tests. It’s perfect for test-driven development, where you write your tests first and then the component.

To activate watch mode, press the watch mode button (the eye icon) in the testing widget:

![Testing widget with watch mode enabled](../_assets/writing-tests/test-widget-watch-mode-enabled.png)

### CI

If you’re not running Storybook Test as part of your CI, you’re missing out on the biggest benefit it provides: catching bugs on PRs before you merge them.

If you are already running `vitest` as part of your CI then your stories should automatically run as tests “for free” when you commit your changes to Git.

If you’re not yet running Vitest in CI, you should set that up. First by adding a new script to your `package.json`:

```json title="package.json"
{
  "scripts": {
    "test-storybook": "vitest --project=storybook"
  }
}
```

Note that this assumes you have a Vitest project called “storybook” for your stories, which is the default configuration when you install Storybook Test. If you’ve renamed it, adjust the script accordingly.

Next, add a new CI workflow.

<details>
<summary>If you use Github Actions that would look like:</summary>

```yaml title=".github/workflows/test-storybook.yml"
name: Storybook Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      # Make sure to grab the latest version of the Playwright image
      # https://playwright.dev/docs/docker#pull-the-image
      image: mcr.microsoft.com/playwright:v1.58.2-noble
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22.12.0

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test-storybook
```

</details>

If you are using a different CI provider, please consult our full [CI guide](https://storybook.js.org/docs/writing-tests/in-ci.md) for more information.

Storybook Test uses Playwright to render your stories by default. For the fastest experience, you should use [a machine image that has Playwright already installed](https://playwright.dev/docs/docker#pull-the-image) (as in the snippet above).

### Coverage

Code coverage provides insight into which code is tested or not. It functions as a guardrail as you develop, to help be sure your work is covered by the proper tests.

In Storybook Test, you can see the coverage provided by your stories in two ways. First, a summary is displayed in the testing widget. Second, clicking that coverage summary will open a full, interactive report.

![Two browser windows. The frontmost one shows the interactive coverage report generated by the Vitest addon. The background one shows the Storybook sidebar with the coverage summary visible in the testing widget.](../_assets/writing-tests/coverage-summary-and-report.png)

In the report, clicking through to a specific component shows the exact branches of code that are covered or not covered:

![Interactive coverage report generated by the Vitest addon, showing the Page component's reported source](../_assets/writing-tests/coverage-report-html-component.png)

Each project’s coverage report will look different, but the important things to note are:

1. **The overall line/branch coverage**, which serves as a high-level health check.
2. **Specific lines/branches** that are not covered, which are potential test gaps.

In our point of view, the goal is not to get 100% coverage and fill every gap, but rather to have a barometer to help you judge code/test changes, and for the gaps to inform you of key states or interactions that are untested. For example, if you’re building a prototype you might skip testing altogether, whereas in a critical app you might want to dot every i and cross every t.

Running coverage analysis can slow down your test runs, so it is turned off by default. To activate coverage, check the coverage checkbox in the testing widget.

![Testing widget with coverage activated](../_assets/writing-tests/test-widget-coverage-enabled.png)

#### Coverage in CI

And while we’re looking at coverage, update your CI workflow to include it:

```diff
- yarn test
+ yarn test --coverage
```

Why are we running all tests (`yarn test`) instead of just the Storybook tests (`yarn test-storybook`)? Because a coverage report is most accurate when accounting for all tests in your project, not just the stories you've written.

Seeing [Storybook-specific coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md#storybook-ui) can be helpful, but in CI output, you want to see the comprehensive coverage of your project.

This way we can track the coverage change in every PR.

Those are the key concepts you’ll need to test in Storybook. Now, let’s look at the different types of tests you can perform.

## Types of tests

Storybook Test supports a variety of testing types to help you validate your work in multiple dimensions.

### Render tests

The most important tool for testing your components in Storybook is stories that render your components in various states.

However, you might not be aware that a basic story is also a [smoke test](https://storybook.js.org/docs/writing-tests/<https://en.wikipedia.org/wiki/Smoke_testing_(software.md)>), which we call a **render test**. The test passes when the story renders successfully and fails when it errors.

![Storybook app showing a failing render test](../_assets/writing-tests/interaction-test-failure-render.png)

Depending on the complexity of your components, you might be able to capture many of your key UI states this way.

### [Interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md)

Render tests are a very basic kind of interaction test. To test stateful components or verify interactive behavior, you define a play function for your story:

```ts
// Dialog.stories.ts — CSF 3
// Replace your-framework with the name of your framework (e.g. react-vite, vue3-vite, etc.)

const meta = {
  component: Dialog,
} satisfies Meta<typeof Dialog>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Opens: Story = {
  play: async ({ canvas, userEvent }) => {
    // Click on a button and assert that a dialog appears
    const button = canvas.getByRole('button', { name: 'Open Modal' });
    await userEvent.click(button);
    await expect(canvas.getByRole('dialog')).toBeInTheDocument();
  },
};
```

```ts
// Dialog.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Dialog,
});

export const Opens = meta.story({
  play: async ({ canvas, userEvent }) => {
    // Click on a button and assert that a dialog appears
    const button = canvas.getByRole('button', { name: 'Open Modal' });
    await userEvent.click(button);
    await expect(canvas.getByRole('dialog')).toBeInTheDocument();
  },
});
```

But `play` functions can also be used for setting up state, creating spies, mocking out the network, simulating user interactions with your components, asserting output, and more. They are the meat and potatoes of testing and are the foundation for the rest of your testing journey in Storybook.

Here’s a more complex example, which includes [spying and mocking](https://storybook.js.org/docs/writing-tests/interaction-testing.md#spying-on-functions-with-fn) via the `fn` utility.

```ts
// EventForm.stories.ts — CSF 3
// Replace your-framework with the name of your framework (e.g. react-vite, vue3-vite, etc.)

const meta = {
  component: EventForm,
} satisfies Meta<typeof EventForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Submits: Story = {
  // Mock functions so we can manipulate and spy on them
  args: {
    getUsers: fn(),
    onSubmit: fn(),
  },
  beforeEach: async ({ args }) => {
    // Manipulate `getUsers` mock to return mocked value
    args.getUsers.mockResolvedValue(users);
  },
  play: async ({ args, canvas, userEvent }) => {
    const usersList = canvas.getAllByRole('listitem');
    await expect(usersList).toHaveLength(4);
    await expect(canvas.getAllByText('VIP')).toHaveLength(2);

    const titleInput = await canvas.findByLabelText('Enter a title for your event');
    await userEvent.type(titleInput, 'Holiday party');

    const submitButton = canvas.getByRole('button', { name: 'Plan event' });
    await userEvent.click(submitButton);

    // Spy on `onSubmit` to verify that it is called correctly
    await expect(args.onSubmit).toHaveBeenCalledWith({
      name: 'Holiday party',
      userCount: 4,
      data: expect.anything(),
    });
  },
};
```

```ts
// EventForm.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: EventForm,
});

export const Submits = meta.story({
  // Mock functions so we can manipulate and spy on them
  args: {
    getUsers: fn(),
    onSubmit: fn(),
  },
  beforeEach: async ({ args }) => {
    // Manipulate `getUsers` mock to return mocked value
    args.getUsers.mockResolvedValue(users);
  },
  play: async ({ args, canvas, userEvent }) => {
    const usersList = canvas.getAllByRole('listitem');
    await expect(usersList).toHaveLength(4);
    await expect(canvas.getAllByText('VIP')).toHaveLength(2);

    const titleInput = await canvas.findByLabelText('Enter a title for your event');
    await userEvent.type(titleInput, 'Holiday party');

    const submitButton = canvas.getByRole('button', { name: 'Plan event' });
    await userEvent.click(submitButton);

    // Spy on `onSubmit` to verify that it is called correctly
    await expect(args.onSubmit).toHaveBeenCalledWith({
      name: 'Holiday party',
      userCount: 4,
      data: expect.anything(),
    });
  },
});
```

For more information on how to write interaction tests and mocks using the `play` function, please see the [interaction testing guide](https://storybook.js.org/docs/writing-tests/interaction-testing.md#writing-interaction-tests).

### [Accessibility tests](https://storybook.js.org/docs/writing-tests/accessibility-testing.md)

Storybook’s [Accessibility (A11y) addon](https://storybook.js.org/addons/@storybook/addon-a11y) runs a set of automated checks on your stories to help ensure your components can be used by all users, regardless of ability or technology they're using. That means supporting requirements such as: keyboard navigation, screen reader support, usable color contrast, etc.

Accessibility is not only the right thing to do, but it is increasingly mandated. For example, the [European accessibility act](https://ec.europa.eu/social/main.jsp?catId=1202) is scheduled to go into law in June 2025. Similarly in the US, laws like the [Americans with Disabilities Act (ADA)](https://www.ada.gov/) and [Section 508 of the Rehabilitation Act](https://www.section508.gov/) apply to many public-facing services.

To activate accessibility checks alongside your component tests, check the Accessibility checkbox in the testing widget.

![Testing widget with accessibility activated](../_assets/writing-tests/test-widget-a11y-enabled.png)

Once activated, you will see accessibility failures in the sidebar.

![Storybook showing a failing accessibility test in both the sidebar story menu and the Accessibility panel](../_assets/writing-tests/test-a11y-overview.png)

Any failures can be debugged in the Accessibility addon panel.

![Storybook app with accessibility panel open, showing violations and an interactive popover on the violating elements in the preview](../_assets/writing-tests/addon-a11y-debug-violations.png)

### [Visual tests](https://storybook.js.org/docs/writing-tests/visual-testing.md)

Visual tests are the most efficient way to test your components. With the click of a button you can take snapshots of every story in your Storybook and compare those snapshots to baselines — last known “good” snapshots. Not only does this allow you to check the appearance of your components, but they are also able to check a large subset of component functionality [without having to write or maintain any test code](https://storybook.js.org/blog/visual-testing-is-the-greatest-trick-in-ui-development/)!

Storybook supports cross-browser visual testing natively using [Chromatic](https://www.chromatic.com/storybook/?ref=storybook_site), a cloud service made by the Storybook team. When you enable visual testing, every story is automatically turned into a test. This gives you instant feedback on UI bugs directly in Storybook.

![Visual test panel with diff](../_assets/writing-tests/vta-changes-found.png)

### [Snapshot tests](https://storybook.js.org/docs/writing-tests/snapshot-testing.md)

In most cases, the other testing types will provide more coverage with less effort. But there are scenarios where it can be helpful to compare the rendered markup of a story against a known baseline. For example, it can help identify markup changes that trigger rendering errors.

## Reusing stories in other testing tools

Stories are made to be reusable, so you can use them as test cases in popular testing tools.

### [End-to-end](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md)

Sometimes you need to test a full workflow, with the full running stack. In those cases, you can still use your stories by importing them within your Playwright or Cypress end-to-end (E2E) tests.

### [Unit](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md)

If you prefer, you can reuse your Storybook stories in a traditional testing environment, like Vitest or Jest.

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests
---

# Interaction tests

In Storybook, interaction tests are built as part of a [story](https://storybook.js.org/docs/writing-stories.md). That story renders the component with the necessary props and context to place it in an initial state. You then use a [play function](https://storybook.js.org/docs/writing-stories/play-function.md) to simulate user behavior like clicks, typing, and submitting a form and then assert on the end result.

You can preview and debug your interaction tests using the Interactions panel in the Storybook UI. They can be automated using the Vitest addon, allowing you to run tests for your project in Storybook, terminal, or CI environments.

## Writing interaction tests

Every story you write can be render tested. A **render test** is a simple version of an interaction test that only tests the ability of a component to render successfully in a given state. That works fine for relatively simple, static components like a Button. But for more complex, interactive components, you can go farther.

You can simulate user behavior and assert on functional aspects like DOM structure or function calls using the `play` function. When a component is tested, the play function is ran and any assertions within it are validated.

In this example, the EmptyForm story tests the render of the LoginForm component and the FilledForm story tests the form submission:

```ts
// LoginForm.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: LoginForm,
} satisfies Meta<typeof LoginForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const EmptyForm: Story = {};

export const FilledForm: Story = {
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};
```

```ts
// LoginForm.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: LoginForm,
});

export const EmptyForm = meta.story();

export const FilledForm = meta.story({
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
});
```

![Storybook with a LoginForm component and passing interactions in the Interactions panel](../_assets/writing-tests/interaction-test-pass.png)

There’s a lot going on in that code sample, so let’s walk through the APIs one-by-one.

### Querying the `canvas`

`canvas` is a queryable element containing the story under test, which is provided as a parameter of your play function. You can use `canvas` to find specific elements to interact with or assert on. All query methods come directly from Testing Library and take the form of `<type><subject>`.

The available types are summarized in this table and fully documented in the [Testing Library docs](https://testing-library.com/docs/queries/about#types-of-queries):

| Type of Query         | 0 Matches     | 1 Match        | >1 Matches   | Awaited |
| --------------------- | ------------- | -------------- | ------------ | ------- |
| **Single Element**    |               |                |              |         |
| `getBy...`            | Throw error   | Return element | Throw error  | No      |
| `queryBy...`          | Return `null` | Return element | Throw error  | No      |
| `findBy...`           | Throw error   | Return element | Throw error  | Yes     |
| **Multiple Elements** |               |                |              |         |
| `getAllBy...`         | Throw error   | Return array   | Return array | No      |
| `queryAllBy...`       | Return `[]`   | Return array   | Return array | No      |
| `findAllBy...`        | Throw error   | Return array   | Return array | Yes     |

The subjects are listed here, with links to their full Testing Library documentation:

1. [`ByRole`](https://testing-library.com/docs/queries/byrole) — Find elements by their accessible role
2. [`ByLabelText`](https://testing-library.com/docs/queries/bylabeltext) — Find elements by their associated label text
3. [`ByPlaceholderText`](https://testing-library.com/docs/queries/byplaceholdertext) — Find elements by their placeholder value
4. [`ByText`](https://testing-library.com/docs/queries/bytext) — Find elements by the text they contain
5. [`ByDisplayValue`](https://testing-library.com/docs/queries/bydisplayvalue) — Find `input`, `textarea`, or `select` elements by their current value
6. [`ByAltText`](https://testing-library.com/docs/queries/byalttext) — Find elements with the given `alt` attribute value
7. [`ByTitle`](https://testing-library.com/docs/queries/bytitle) — Find elements with the given `title` attribute value
8. [`ByTestId`](https://testing-library.com/docs/queries/bytestid) — Find elements with the given `data-testid` attribute value

Note the order of this list! We (and [Testing Libary](https://testing-library.com/docs/queries/about#priority)) highly encourage you to query for elements in a way that resembles the way a real person would interact with your UI. For example, finding elements by their accessible role helps ensure that the most people can use your component. While using `data-testid` should be a last resort, only after trying every other approach.

Putting that altogether, some typical queries might look like:

```js
// Find the first element with a role of button with the accessible name "Submit"
await canvas.findByRole('button', { name: 'Submit' });

// Get the first element with the text "An example heading"
canvas.getByText('An example heading');

// Get all elements with the role of listitem
canvas.getAllByRole('listitem');
```

### Simulating behavior with `userEvent`

After querying for elements, you will likely need to interact with them to test your component’s behavior. For this we use the `userEvent` utility, which is provided as a parameter of your play function. This utility simulates user interactions with the component, such as clicking buttons, typing in inputs, and selecting options.

There are many methods available on `userEvent`, which are detailed in the [`user-event` documentation](https://testing-library.com/docs/user-event/intro#writing-tests-with-userevent). This table will highlight some of the commonly-used methods.

| Method            | Description                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `click`           | Clicks the element, calling a click() function<br />`await userEvent.click(<element>)`                                   |
| `dblClick`        | Clicks the element twice<br />`await userEvent.dblClick(<element>)`                                                      |
| `hover`           | Hovers an element<br />`await userEvent.hover(<element>)`                                                                |
| `unhover`         | Unhovers out of element<br />`await userEvent.unhover(<element>)`                                                        |
| `tab`             | Presses the tab key<br />`await userEvent.tab()`                                                                         |
| `type`            | Writes text inside inputs or textareas<br />`await userEvent.type(<element>, 'Some text');`                              |
| `keyboard`        | Simulates keyboard events<br />`await userEvent.keyboard('{Shift}');`                                                    |
| `selectOptions`   | Selects the specified option(s) of a select element<br />`await userEvent.selectOptions(<element>, ['1','2']);`          |
| `deselectOptions` | Removes the selection from a specific option of a select element<br />`await userEvent.deselectOptions(<element>, '1');` |
| `clear`           | Selects the text inside inputs or textareas and deletes it<br />`await userEvent.clear(<element>);`                      |

`userEvent` methods should _always_ be `await`ed inside of the play function. This ensures they can be properly logged and debugged in the Interactions panel.

### Asserting with `expect`

Finally, after querying for elements and simulating behavior, you can make assertions on the result which are validated when running the test. For this we use the `expect` utility, which is available via the `storybook/test` module:

```js

```

The `expect` utility here combines the methods available in [Vitest’s `expect`](https://vitest.dev/api/expect.html) as well as those from [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom#custom-matchers) (which, despite the name, also work in Vitest tests). There are many, many methods available. This table will highlight some of the commonly-used methods.

| Method                                                                                 | Description                                                                                                                          |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [`toBeInTheDocument()`](https://github.com/testing-library/jest-dom#tobeinthedocument) | Checks if the element is in the DOM<br />`await expect(<element>).toBeInTheDocument()`                                               |
| [`toBeVisible()`](https://github.com/testing-library/jest-dom#tobevisible)             | Checks if the element is visible to the user<br />`await expect(<element>).toBeVisible()`                                            |
| [`toHaveAttribute()`](https://github.com/testing-library/jest-dom#tohaveattribute)     | Checks if an element has an attribute<br />`await expect(<element>).toHaveAttribute('aria-disabled', 'true')`                        |
| [`toHaveBeenCalled()`](https://vitest.dev/api/expect.html#tohavebeencalled)            | Checks that a spied function was called<br />`await expect(<function-spy>).toHaveBeenCalled()`                                       |
| [`toHaveBeenCalledWith()`](https://vitest.dev/api/expect.html#tohavebeencalledwith)    | Checks that a spied function was called with specific parameters<br />`await expect(<function-spy>).toHaveBeenCalledWith('example')` |

`expect` calls should _always_ be `await`ed inside of the play function. This ensures they can be properly logged and debugged in the Interactions panel.

### Spying on functions with `fn`

When your component calls a function, you can spy on that function to make assertions on its behavior using the `fn` utility from Vitest, available via the `storybook/test` module:

```js

```

Most of the time, you will use `fn` as an `arg` value when writing your story, then access that `arg` in your test:

```ts
// LoginForm.stories.ts — CSF 3
// Replace your-framework with the name of your framework (e.g. react-vite, vue3-vite, etc.)

const meta = {
  component: LoginForm,
  args: {
    // 👇 Use `fn` to spy on the onSubmit arg
    onSubmit: fn(),
  },
} satisfies Meta<typeof LoginForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const FilledForm: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.type(canvas.getByLabelText('Email'), 'email@provider.com');
    await userEvent.type(canvas.getByLabelText('Password'), 'a-random-password');
    await userEvent.click(canvas.getByRole('button', { name: 'Log in' }));

    // 👇 Now we can assert that the onSubmit arg was called
    await expect(args.onSubmit).toHaveBeenCalled();
  },
};
```

```ts
// LoginForm.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: LoginForm,
  args: {
    // 👇 Use `fn` to spy on the onSubmit arg
    onSubmit: fn(),
  },
});

export const FilledForm = meta.story({
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.type(canvas.getByLabelText('Email'), 'email@provider.com');
    await userEvent.type(canvas.getByLabelText('Password'), 'a-random-password');
    await userEvent.click(canvas.getByRole('button', { name: 'Log in' }));

    // 👇 Now we can assert that the onSubmit arg was called
    await expect(args.onSubmit).toHaveBeenCalled();
  },
});
```

### Run code before the component gets rendered

You can execute code before rendering by using the `mount` function in the `play` method.

Here's an example of using the [`mockdate`](https://github.com/boblauer/MockDate) package to mock the [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), a useful way to make your story render in a consistent state.

```ts
// Page.stories.ts — CSF 3

// ...rest of story file

export const ChristmasUI: Story = {
  async play({ mount }) {
    MockDate.set('2024-12-25');
    // 👇 Render the component with the mocked date
    await mount();
    // ...rest of test
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Page,
});

export const ChristmasUI = meta.story({
  async play({ mount }) {
    MockDate.set('2024-12-25');
    // 👇 Render the component with the mocked date
    await mount();
    // ...rest of test
  },
});
```

There are two requirements to use the `mount` function:

1. You _must_ destructure the mount property from the `context` (the argument passed to your play function). This makes sure that Storybook does not start rendering the story before the play function begins.
2. Your Storybook framework or builder must be configured to transpile to ES2017 or newer. This is because destructuring statements and async/await usages are otherwise transpiled away, which prevents Storybook from recognizing your usage of `mount`.

#### Create mock data before rendering

You can also use `mount` to create mock data that you want to pass to the component. To do so, first create your data in the play function and then call the `mount` function with a component configured with that data. In this example, we create a mock `note` and pass its `id` to the Page component, which we call `mount` with.

```tsx
// Page.stories.tsx — CSF 3
// Replace your-framework with the framework you are using, e.g., react-vite, nextjs, nextjs-vite, etc.

// 👇 Automocked module resolves to '../lib/__mocks__/db'

const meta = { component: Page } satisfies Meta<typeof Page>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  play: async ({ mount, args, userEvent }) => {
    const note = await db.note.create({
      data: { title: 'Mount inside of play' },
    });

    const canvas = await mount(
      // 👇 Pass data that is created inside of the play function to the component
      //   For example, a just-generated UUID
      ,
    );

    await userEvent.click(await canvas.findByRole('menuitem', { name: /login to add/i }));
  },
  argTypes: {
    // 👇 Make the params prop un-controllable, as the value is always overridden in the play function.
    params: { control: { disable: true } },
  },
};
```

```tsx
// Page.stories.tsx — CSF Next 🧪

// 👇 Automocked module resolves to '../lib/__mocks__/db'

const meta = preview.meta({ component: Page });

export const Basic = meta.story({
  play: async ({ mount, args, userEvent }) => {
    const note = await db.note.create({
      data: { title: 'Mount inside of play' },
    });

    const canvas = await mount(
      // 👇 Pass data that is created inside of the play function to the component
      //   For example, a just-generated UUID
      ,
    );

    await userEvent.click(await canvas.findByRole('menuitem', { name: /login to add/i }));
  },
  argTypes: {
    // 👇 Make the params prop un-controllable, as the value is always overridden in the play function.
    params: { control: { disable: true } },
  },
});
```

When you call `mount()` with no arguments, the component is rendered using the story’s render function, whether the [implicit default](https://storybook.js.org/docs/api/csf/index.md#default-render-functions) or the [explicit custom definition](https://storybook.js.org/docs/api/csf/index.md#custom-render-functions).

When you mount a specific component inside the `mount` function like in the example above, the story’s render function will be ignored. This is why you must forward the `args` to the component.

### Run code before each story in a file

Sometimes you might need to run the same code before each story in a file. For instance, you might need to set up the initial state of the component or modules. You can do this by adding an asynchronous `beforeEach` function to the component meta.

You can return a cleanup function from the `beforeEach` function, which will run **after** each story, when the story is remounted or navigated away from.

Generally, you should reset component and module state in the [preview file's `beforeAll` or `beforeEach` functions](#set-up-or-reset-state-for-all-tests), to ensure it applies to your entire project. However, if a component's needs are particularly unique, you can use the returned cleanup function in the component meta `beforeEach` to reset the state as needed.

```ts
// Page.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Page,
  // 👇 Set the value of Date for every story in the file
  async beforeEach() {
    MockDate.set('2024-02-14');

    // 👇 Reset the Date after each story
    return () => {
      MockDate.reset();
    };
  },
} satisfies Meta<typeof Page>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  async play({ canvas }) {
    // ... This will run with the mocked Date
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Page,
  // 👇 Set the value of Date for every story in the file
  async beforeEach() {
    MockDate.set('2024-02-14');

    // 👇 Reset the Date after each story
    return () => {
      MockDate.reset();
    };
  },
});

export const Basic = meta.story({
  async play({ canvas }) {
    // ... This will run with the mocked Date
  },
});
```

### Set up or reset state for all tests

When you [alter a component's state](#run-code-before-the-component-gets-rendered), it's important to reset that state before rendering another story to maintain isolation between tests.

There are two options for resetting state, `beforeAll` and `beforeEach`.

#### `beforeAll`

The `beforeAll` function in the preview file (`.storybook/preview.*`) will run once before any stories in the project and will _not_ re-run between stories. Beyond its initial run when kicking off a test run, it will not run again unless the preview file is updated. This is a good place to bootstrap your project or run any setup that your entire project depends on, as in the example below.

You can return a cleanup function from the `beforeAll` function, which will run before re-running the `beforeAll` function or during the teardown process in the test runner.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  async beforeAll() {
    await init();
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  async beforeAll() {
    await init();
  },
});
```

#### `beforeEach`

Unlike `beforeAll`, which runs only once, the `beforeEach` function in the preview file (`.storybook/preview.*`) will run before each story in the project. This is best used for resetting state or modules that are used by all or most of your stories. In the example below, we use it to reset the mocked Date.

You can return a cleanup function from the `beforeEach` function, which will run **after** each story, when the story is remounted or navigated away from.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  async beforeEach() {
    MockDate.reset();
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  async beforeEach() {
    MockDate.reset();
  },
});
```

It is _not_ necessary to restore `fn()` mocks, as Storybook will already do that automatically before rendering a story. See the [`parameters.test.restoreMocks` API](https://storybook.js.org/docs/api/parameters.md#restoremocks) for more information.

### Make assertions after interactions

Sometimes, you may need to make assertions or run code after the component has been rendered and interacted with.

#### `afterEach`

`afterEach` runs after the story is rendered and the play function has completed. It can be used at the project level in the preview file (`.storybook/preview.*`), at the component level in the component meta, or at the story level in the story definition. This is useful for making assertions after the component has been rendered and interacted with, such as running checks on the final rendered output or logging information.

Like the `play` function, `afterEach` receives the `context` object, which contains the `args`, `canvas`, and other properties related to the story. You can use this to make assertions or run code after the story has been rendered.

```ts
// Page.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Page,
  // 👇 Runs after each story in this file
  async afterEach(context) {
    console.log(`✅ Tested ${context.name} story`);
  },
} satisfies Meta<typeof Page>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  async play({ canvas }) {
    // ...
  },
};
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Page,
  // 👇 Runs after each story in this file
  async afterEach(context) {
    console.log(`✅ Tested ${context.name} story`);
  },
});

export const Basic = meta.story({
  async play({ canvas }) {
    // ...
  },
});
```

You should not use `afterEach` to reset state in your tests. Because it runs after the story, resetting state here could prevent you from seeing the correct end state of your story. Instead, use the [`beforeEach`'s returned cleanup function](#beforeeach) to reset state, which will run only when navigating between stories to preserve the end state.

### Group interactions with the step function

For complex flows, it can be worthwhile to group sets of related interactions together using the step function. This allows you to provide a custom label that describes a set of interactions:

```ts
// MyComponent.stories.ts — CSF 3
// ...rest of story file

export const Submitted: Story = {
  play: async ({ args, canvas, step, userEvent }) => {
    await step('Enter email and password', async () => {
      await userEvent.type(canvas.getByTestId('email'), 'hi@example.com');
      await userEvent.type(canvas.getByTestId('password'), 'supersecret');
    });

    await step('Submit form', async () => {
      await userEvent.click(canvas.getByRole('button'));
    });
  },
};
```

```ts
// MyComponent.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const Submitted = meta.story({
  play: async ({ args, canvas, step }) => {
    await step('Enter email and password', async () => {
      await userEvent.type(canvas.getByTestId('email'), 'hi@example.com');
      await userEvent.type(canvas.getByTestId('password'), 'supersecret');
    });

    await step('Submit form', async () => {
      await userEvent.click(canvas.getByRole('button'));
    });
  },
});
```

This will show your interactions nested in a collapsible group:

![Interaction testing with labeled steps](../_assets/writing-tests/storybook-addon-interactions-steps.png)

### Mocked modules

If your component depends on modules that are imported into the component file, you can mock those modules to control and assert on their behavior. This is detailed in the [mocking modules guide](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules.md).
You can then import the mocked module (which has all of the helpful methods of a [Vitest mocked function](https://vitest.dev/api/mock.html)) into your story and use it to assert on the behavior of your component:

```ts
// NoteUI.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// 👇 Automocked module resolves to '../app/__mocks__/actions'

const meta = { component: NoteUI } satisfies Meta<typeof NoteUI>;
export default meta;

type Story = StoryObj<typeof meta>;

const notes = createNotes();

export const SaveFlow: Story = {
  name: 'Save Flow ▶',
  args: {
    isEditing: true,
    note: notes[0],
  },
  play: async ({ canvas, userEvent }) => {
    const saveButton = canvas.getByRole('menuitem', { name: /done/i });
    await userEvent.click(saveButton);
    // 👇 This is the mock function, so you can assert its behavior
    await expect(saveNote).toHaveBeenCalled();
  },
};
```

```ts
// NoteUI.stories.ts — CSF Next 🧪

// 👇 Automocked module resolves to '../app/__mocks__/actions'

const meta = preview.meta({ component: NoteUI });

const notes = createNotes();

export const SaveFlow = meta.story({
  name: 'Save Flow ▶',
  args: {
    isEditing: true,
    note: notes[0],
  },
  play: async ({ canvas, userEvent }) => {
    const saveButton = canvas.getByRole('menuitem', { name: /done/i });
    await userEvent.click(saveButton);
    // 👇 This is the mock function, so you can assert its behavior
    await expect(saveNote).toHaveBeenCalled();
  },
});
```

## Running interaction tests

If you're using the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), you can run your interaction tests in these ways:

- [In the Storybook UI](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#storybook-ui)
- [In your editor](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#editor-extension)
- [Via the CLI](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#cli)
- [In CI environments](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#in-ci)

In the Storybook UI, you can run interaction tests by clicking the **Run component tests** button in the expanded testing widget in the sidebar or by opening the context menu (three dots) on a story or folder and selecting **Run component tests**.

![Test widget, expanded, hovering run component tests button](../_assets/writing-tests/test-widget-run-component-tests.png)

If you're using the [test-runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md), you can run your interaction tests in the terminal or in CI environments.

## Debugging interaction tests

If you check the Interactions panel, you'll see the step-by-step flow defined in your play function for each story. It also offers a handy set of UI controls to pause, resume, rewind, and step through each interaction.

Any test failures will also show up here, making it easy to quickly pinpoint the exact point of failure. In this example, the logic is missing to set the `submitted` state after pressing the Log in button.

### Permalinks for reproductions

Because Storybook is a webapp, anyone with the URL can reproduce the failure with the same detailed information without any additional environment configuration or tooling required.

![Interaction testing with a failure](../_assets/writing-tests/interactions-failure.png)

Streamline interaction testing further by automatically [publishing Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md) in pull requests. That gives teams a universal reference point to test and debug stories.

## Automate with CI

When you run your tests with the Vitest addon, automating those tests is as simple as running your tests in your CI environment. Please see the [testing in CI guide](https://storybook.js.org/docs/writing-tests/in-ci.md) for more information.

If you cannot use the Vitest addon, you can still run your tests in CI using the [test-runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md).

## Troubleshooting

### What’s the difference between interaction tests and visual tests?

Interaction tests can be expensive to maintain when applied wholesale to every component. We recommend combining them with other methods like visual testing for comprehensive coverage with less maintenance work.

### What's the difference between interaction tests and using Vitest + Testing Library alone?

Interaction tests integrate Vitest and Testing Library into Storybook. The biggest benefit is the ability to view the component you're testing in a real browser. That helps you debug visually, instead of getting a dump of the (fake) DOM in the command line or hitting the limitations of how JSDOM mocks browser functionality. It's also more convenient to keep stories and tests together in one file than having them spread across files.

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests/interaction-testing
---

# Accessibility tests

Web accessibility is the practice of making websites and apps accessible and inclusive to all people, regardless of ability or the technology they’re using. That means supporting requirements such as keyboard navigation, screen reader support, sufficient color contrast, etc.

Accessibility is not only the right thing to do, but it is increasingly mandated. For example, the [European Accessibility Act](https://ec.europa.eu/social/main.jsp?catId=1202) imposes specific accessibility requirements. Similarly in the US, laws like the [Americans with Disabilities Act (ADA)](https://www.ada.gov/) and [Section 508 of the Rehabilitation Act](https://www.section508.gov/) apply to many public-facing services. Many of these laws are based on [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/), a standardized guideline for making web content accessible.

Accessibility tests audit the rendered DOM against a set of heuristics based on WCAG rules and other industry-accepted best practices. They act as the first line of QA to catch blatant accessibility violations.

## Install the addon

Storybook provides an Accessibility (a11y) addon to help ensure the accessibility of your components. It is built on top of Deque’s [axe-core library](https://github.com/dequelabs/axe-core), which automatically catches [up to 57% of WCAG issues](https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/).

Run this command to install and configure the addon in your project:

```shell
npx storybook add @storybook/addon-a11y
```

```shell
pnpm exec storybook add @storybook/addon-a11y
```

```shell
yarn exec storybook add @storybook/addon-a11y
```

Storybook's [`add`](https://storybook.js.org/docs/api/cli-options.md#add) command automates the addon's installation and setup. To install it manually, see our [documentation](https://storybook.js.org/docs/addons/install-addons.md#manual-installation) on how to install addons.

Your Storybook will now include some features to check the accessibility of your components, including a button in the toolbar to simulate different vision impairments and an Accessibility addon panel to check for violations.

![Storybook UI with accessibility features annotated](../_assets/writing-tests/addon-a11y-annotated.png)

### Integration with Vitest addon

The accessibility addon is designed to integrate with the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), so that you can [run accessibility tests](#run-accessibility-tests) alongside your component tests.

To get started, run this command, which will install and configure the Vitest addon and Vitest:

```shell
npx storybook add @storybook/addon-vitest
```

```shell
pnpm exec storybook add @storybook/addon-vitest
```

```shell
yarn exec storybook add @storybook/addon-vitest
```

The full installation instructions, including project requirements, are available in the [Vitest addon documentation](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#install-and-set-up).

## Check for violations

When you navigate to a story, automated accessibility checks are run and the results are reported in the Accessibility addon panel.

The results are broken down into three sub-tabs:

- **Violations** are known violations of WCAG rules and best practices
- **Passes** are known non-violations
- **Incomplete** highlights areas that you should confirm manually because they could not be checked automatically

## Configure

Because the addon is built on top of `axe-core`, much of the configuration available maps to its available options:

| Property                  | Default     | Description                                                                                                                                                                                              |
| ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters.a11y.context` | `'body'`    | [Context](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter) passed to `axe.run`. Defines which elements to run checks against.                                            |
| `parameters.a11y.config`  | (see below) | Configuration passed to [`axe.configure()`](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure). Most commonly used to [configure individual rules](#individual-rules). |
| `parameters.a11y.options` | `{}`        | [Options](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter) passed to `axe.run`. Can be used to adjust the rulesets checked against.                                      |
| `parameters.a11y.test`    | `undefined` | Determines test behavior when run with the Vitest addon. [More details below](#test-behavior).                                                                                                           |
| `globals.a11y.manual`     | `undefined` | Set to `true` to prevent stories from being automatically analyzed when visited. [More details below](#disable-automated-checks)                                                                         |

<details>
<summary>Default `parameters.a11y.config`</summary>

By default, Storybook disables the [region rule](https://dequeuniversity.com/rules/axe/4.10/region?application=RuleDescription), which does not typically apply to components in stories and can lead to false negatives.

```js
{
  rules: [
    {
      id: 'region',
      enabled: false,
    },
  ],
}
```

</details>

We’ll share examples to show how to use some of these configuration properties.

Here, they are applied to all stories in a project, in `.storybook/preview.*`:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    a11y: {
      /*
       * Axe's context parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter
       * to learn more. Typically, this is the CSS selector for the part of the DOM you want to analyze.
       */
      context: 'body',
      /*
       * Axe's configuration
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
       * to learn more about the available properties.
       */
      config: {},
      /*
       * Axe's options parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
       * to learn more about the available options.
       */
      options: {},
    },
  },
  initialGlobals: {
    a11y: {
      // Optional flag to prevent the automatic check
      manual: true,
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonA11y()],
  parameters: {
    a11y: {
      /*
       * Axe's context parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter
       * to learn more. Typically, this is the CSS selector for the part of the DOM you want to analyze.
       */
      context: 'body',
      /*
       * Axe's configuration
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
       * to learn more about the available properties.
       */
      config: {},
      /*
       * Axe's options parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
       * to learn more about the available options.
       */
      options: {},
    },
  },
  initialGlobals: {
    a11y: {
      // Optional flag to prevent the automatic check
      manual: true,
    },
  },
});
```

You can also apply the configuration for all stories in a file (in the `meta`) or an individual story:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  parameters: {
    a11y: {
      /*
       * Axe's context parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter
       * to learn more.
       */
      context: {},
      /*
       * Axe's configuration
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
       * to learn more about the available properties.
       */
      config: {},
      /*
       * Axe's options parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
       * to learn more about the available options.
       */
      options: {},
      /*
       * Configure test behavior
       * See: https://storybook.js.org/docs/next/writing-tests/accessibility-testing#test-behavior
       */
      test: 'error',
    },
  },
  globals: {
    a11y: {
      // Optional flag to prevent the automatic check
      manual: true,
    },
  },
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

export const ExampleStory: Story = {
  parameters: {
    a11y: {
      // ...same config available as above
    },
  },
  globals: {
    a11y: {
      // ...same config available as above
    },
  },
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    a11y: {
      /*
       * Axe's context parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter
       * to learn more.
       */
      context: {},
      /*
       * Axe's configuration
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
       * to learn more about the available properties.
       */
      config: {},
      /*
       * Axe's options parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
       * to learn more about the available options.
       */
      options: {},
      /*
       * Configure test behavior
       * See: https://storybook.js.org/docs/next/writing-tests/accessibility-testing#test-behavior
       */
      test: 'error',
    },
  },
  globals: {
    a11y: {
      // Optional flag to prevent the automatic check
      manual: true,
    },
  },
});

export const ExampleStory = meta.story({
  parameters: {
    a11y: {
      // ...same config available as above
    },
  },
  globals: {
    a11y: {
      // ...same config available as above
    },
  },
});
```

### Rulesets

The addon uses the `axe-core` library to run accessibility checks. By default, it runs a set of rules that are based on the WCAG 2.0 and 2.1 guidelines, as well as some best practices:

- [WCAG 2.0 Level A & AA Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md#wcag-20-level-a--aa-rules)
- [WCAG 2.1 Level A & AA Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md#wcag-21-level-a--aa-rules)
- [Best Practices Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md#best-practices-rules)

You can find a breakdown of these rulesets, as well as the other rulesets available in [axe-core’s documentation](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md#wcag-2x-level-aaa-rules).

To change the rules that are checked against (e.g. to check against WCAG 2.2 AA or WCAG 2.x AAA rules), use the [`runOnly` option](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    a11y: {
      options: {
        /*
         * Opt in to running WCAG 2.x AAA rules
         * Note that you must explicitly re-specify the defaults (all but the last array entry)
         * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples for more details
         */
        runOnly: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice', 'wcag2aaa'],
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonA11y()],
  parameters: {
    a11y: {
      options: {
        /*
         * Opt in to running WCAG 2.x AAA rules
         * Note that you must explicitly re-specify the defaults (all but the last array entry)
         * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples for more details
         */
        runOnly: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice', 'wcag2aaa'],
      },
    },
  },
});
```

### Individual rules

You can also enable, disable, or configure individual rules. This can be done in the `config` property of the `parameters.a11y` object. For example:

```ts
// Button.stories.ts — CSF 3
// ...rest of story file

export const IndividualA11yRulesExample: Story = {
  parameters: {
    a11y: {
      config: {
        rules: [
          {
            // The autocomplete rule will not run based on the CSS selector provided
            id: 'autocomplete-valid',
            selector: '*:not([autocomplete="nope"])',
          },
          {
            // Setting the enabled option to false will disable checks for this particular rule on all stories.
            id: 'image-alt',
            enabled: false,
          },
        ],
      },
    },
  },
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const IndividualA11yRulesExample = meta.story({
  parameters: {
    a11y: {
      config: {
        rules: [
          {
            // The autocomplete rule will not run based on the CSS selector provided
            id: 'autocomplete-valid',
            selector: '*:not([autocomplete="nope"])',
          },
          {
            // Setting the enabled option to false will disable checks for this particular rule on all stories.
            id: 'image-alt',
            enabled: false,
          },
        ],
      },
    },
  },
});
```

### Test behavior

You can configure accessibility tests with the `parameters.a11y.test` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md), which determines the behavior of accessibility tests for a story when run with either the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) or the [test-runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md). The parameter accepts three values:

| Value     | Description                                                                              |
| --------- | ---------------------------------------------------------------------------------------- |
| `'off'`   | Do not run accessibility tests (you can still manually verify via the addon panel)       |
| `'todo'`  | Run accessibility tests; violations return a warning in the Storybook UI                 |
| `'error'` | Run accessibility tests; violations return a failing test in the Storybook UI and CLI/CI |

Like other parameters, you can define it at the project level in `.storybook/preview.*`, the component level in the meta (or default export) of the story file, or the individual story level. For example, to fail on accessibility tests for all stories in a file except one:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  parameters: {
    // 👇 Applies to all stories in this file
    a11y: { test: 'error' },
  },
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

// 👇 This story will use the 'error' value and fail on accessibility violations
export const Primary: Story = {
  args: { primary: true },
};

// 👇 This story will not fail on accessibility violations
//    (but will still run the tests and show warnings)
export const NoA11yFail: Story = {
  parameters: {
    a11y: { test: 'todo' },
  },
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    // 👇 Applies to all stories in this file
    a11y: { test: 'error' },
  },
});

// 👇 This story will use the 'error' value and fail on accessibility violations
export const Primary = meta.story({
  args: { primary: true },
});

// 👇 This story will not fail on accessibility violations
//    (but will still run the tests and show warnings)
export const NoA11yFail = meta.story({
  parameters: {
    a11y: { test: 'todo' },
  },
});
```

Why is the value called "todo" instead of "warn"? This value is intended to serve as a literal `TODO` in your codebase. It can be used to mark stories that you know have accessibility issues but are not ready to fix yet. This way, you can keep track of them and address them later.

The `'off'` value should only be used for stories that do not need to be tested for accessibility, such as one used to demonstrate an antipattern in a component's usage.

You can also [disable individual rules](#individual-rules) when they are not applicable to your use case.

### Excluded elements

Sometimes, it may be necessary to exclude certain elements from the accessibility checks. For this, you can define a custom [context](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter) to select which elements are included (or excluded) when running checks. For example, this story will ignore elements with the class `no-a11y-check`:

```ts
// Button.stories.ts — CSF 3
// ...rest of story file

export const ExampleStory: Story = {
  parameters: {
    a11y: {
      /*
       * Axe's context parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter
       * to learn more.
       */
      context: {
        include: ['body'],
        exclude: ['.no-a11y-check'],
      },
    },
  },
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const ExampleStory = meta.story({
  parameters: {
    a11y: {
      /*
       * Axe's context parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter
       * to learn more.
       */
      context: {
        include: ['body'],
        exclude: ['.no-a11y-check'],
      },
    },
  },
});
```

### Disable automated checks

When you disable automated accessibility checks, the addon will not run any tests when you navigate to a story or when you [run the tests with the Vitest addon](#run-accessibility-tests). You can still manually trigger checks in the Accessibility addon panel. This is useful for stories that are not meant to be accessible, such as those demonstrating an antipattern or a specific use case.

Disable automated accessibility checks for stories or components by adding the following globals to your stories or meta (or default export):

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const NonA11yStory: Story = {
  globals: {
    a11y: {
      // This option disables all automatic a11y checks on this story
      manual: true,
    },
  },
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const NonA11yStory = meta.story({
  globals: {
    a11y: {
      // This option disables all automatic a11y checks on this story
      manual: true,
    },
  },
});
```

## Run accessibility tests

### With the Vitest addon

If you're using the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), you can run your accessibility tests, as part of component tests, in these ways:

- [In the Storybook UI](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#storybook-ui)
- [In CI environments](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#in-ci)

To run accessibility tests in the Storybook UI, first expand the testing widget in the sidebar and check the Accessibility checkbox. Now, when you press the Run component tests button, the accessibility tests will be run along with any other tests you have configured.

![Test widget, expanded, with accessibility checked](../_assets/writing-tests/test-widget-a11y-enabled.png)

After running the tests, you will see the results in the sidebar, which will add a test status indicator next to each story that was tested. You can press on these indicators to open a menu with the Accessibility test result. Pressing on that result will navigate to that story and open the Accessibility panel, where you view details about each violation and suggestions toward how to fix them.

![Storybook showing a failing accessibility test in both the sidebar story menu and the Accessibility panel](../_assets/writing-tests/test-a11y-overview.png)

If any of your tests have warnings or failures, the testing widget will show the number of warnings and failures. You can press on these to filter the stories in the sidebar to only show those with warnings or failures.

In CI, accessibility tests are run automatically for stories with [`parameters.a11y.test = 'error'`](#test-behavior) when you run the Vitest tests.

### With the test-runner

If you're using the [test-runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md), you can run your accessibility tests in the terminal or in CI environments.

Accessibility tests are included in your test run when you have the Accessibility addon installed and [`parameters.a11y.test`](#test-behavior) is set to a value other than `'off'`.

## Debug accessibility violations

When you run accessibility tests, the results are reported in the Storybook UI. You can click on a violation to see more details about it, including the rule that was violated and suggestions for how to fix it.

You can also toggle on highlighting in the Storybook UI to see which elements are causing the violation, and click on a highlighted element to see the violations details in a popover menu.

![Storybook UI with a highlighted element with a popover menu showing accessbility violation details](../_assets/writing-tests/addon-a11y-debug-violations.png)

## Automate with CI

When you run your accessibility tests with the Vitest addon, automating them is as simple as running them in your CI environment. For more information, please see the [testing in CI guide](https://storybook.js.org/docs/writing-tests/in-ci.md).

Accessibility tests will only produce errors in CI if you have set [`parameters.a11y.test`](#test-behavior) to `'error'`. If you set it to `'todo'`, there will be no accessibility-related errors, warnings, or output in CI, but you can still see the results as warnings in the Storybook UI when you run the tests locally.

If you cannot use the Vitest addon, you can still run your tests in CI using the [test-runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md).

## Recommended workflow

You can use configuration to progressively work toward a more accessible UI by combining multiple test behaviors. For example, you can start with `'error'` to fail on accessibility violations, then switch to `'todo'` to mark components that need fixing, and finally remove the todos once all stories pass accessibility tests:

1. Update your project configuration to fail on accessibility violations by setting [`parameters.a11y.test`](#test-behavior) to `'error'`. This ensures that all new stories are tested to meet accessibility standards.
   ```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    // 👇 Fail all accessibility tests when violations are found
    a11y: { test: 'error' },
  },
};
export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonA11y()],
  parameters: {
    // 👇 Fail all accessibility tests when violations are found
    a11y: { test: 'error' },
  },
});
```
2. You will likely find that many components have accessibility failures (and maybe feel a bit overwhelmed!).
3. Take note of the components with accessibility issues and temporarily reduce their failures to warnings by applying the `'todo'` parameter value. This keeps accessibility issues visible while not blocking development. This is also a good time to commit your work as a baseline for future improvements.
   ```ts
// DataTable.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: DataTable,
  parameters: {
    // 👇 This component's accessibility tests will not fail
    //    Instead, they display warnings in the Storybook UI
    a11y: { test: 'todo' },
  },
} satisfies Meta<typeof DataTable>;
export default meta;
```

```ts
// DataTable.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: DataTable,
  parameters: {
    // 👇 This component's accessibility tests will not fail
    //    Instead, they display warnings in the Storybook UI
    a11y: { test: 'todo' },
  },
});
```
4. Pick a good starting point from the components you just marked `'todo'` (we recommend starting with something like Button, as it's a fundamental component used within many others). Fix the issues in that component using the suggestions in the addon panel to ensure it passes accessibility tests, then remove the parameter.
   ```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  parameters: {
    // 👇 Remove this once all stories pass accessibility tests
    // a11y: { test: 'todo' },
  },
} satisfies Meta<typeof Button>;
export default meta;
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    // 👇 Remove this once all stories pass accessibility tests
    // a11y: { test: 'todo' },
  },
});
```
5. Pick another component and repeat the process until you've covered all your components and you're an accessibility hero!

## FAQ

### What’s the difference between browser-based and linter-based accessibility tests?

Browser-based accessibility tests, like those found in Storybook, evaluate the rendered DOM because that gives you the highest accuracy. Auditing code that hasn't been compiled yet is one step removed from the real thing, so you won't catch everything the user might experience.

### Why are my tests failing in different environments?

With the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), your tests run in Vitest using your project's configuration with Playwright's Chromium browser. This can lead to inconsistent test results reported in the Storybook UI or CLI. The inconsistency can be due to `axe-core` reporting different results in different environments, such as browser versions or configurations. If you encounter this issue, we recommend reaching out using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help), [Github issues](https://github.com/storybookjs/storybook/issues/new?template=bug_report.yml)).

### The addon panel does not show expected violations

Modern React components often use asynchronous techniques like [Suspense](https://react.dev/reference/react/Suspense) or [React Server Components (RSC)](https://react.dev/reference/rsc/server-components) to handle complex data fetching and rendering. These components don’t immediately render their final UI state. Storybook doesn’t inherently know when an async component has fully rendered. As a result, the a11y checks sometimes run too early, before the component finishes rendering, leading to false negatives (no reported violations even if they exist).

To address this issue, we have introduced a feature flag: `developmentModeForBuild`. This feature flag allows you to set `process.env.NODE_ENV` to `'development'` in built Storybooks, enabling development-related optimizations that are typically disabled in production builds. One of those development optimizations is React’s [`act` utility](https://react.dev/reference/react/act), which helps ensure that all updates related to a test are processed and applied before making assertions, like a11y checks.

To enable this feature flag, add the following configuration to your `.storybook/main.js|ts` file:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    developmentModeForBuild: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    developmentModeForBuild: true,
  },
});
```

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests/accessibility-testing
---

# Visual tests

Visual tests are the most efficient way to test your components. With the click of a button you can take snapshots of every story in your Storybook and compare those snapshots to baselines — last known “good” snapshots. Not only does this allow you to check the appearance of your components, but they are also able to check a large subset of component functionality [without having to write or maintain any test code](https://storybook.js.org/blog/visual-testing-is-the-greatest-trick-in-ui-development/)!

Storybook supports cross-browser visual testing natively using [Chromatic](https://www.chromatic.com/storybook/?ref=storybook_site), a cloud service made by the Storybook team. When you enable visual testing, every story is automatically turned into a test. This gives you instant feedback on UI bugs directly in Storybook.

## Install the addon

Add visual tests to your project by installing `@chromatic-com/storybook`, the official addon by Storybook maintainers:

```shell
npx storybook@latest add @chromatic-com/storybook
```

```shell
pnpm dlx storybook@latest add @chromatic-com/storybook
```

```shell
yarn dlx storybook@latest add @chromatic-com/storybook
```

## Enable visual tests

When you start Storybook, you'll see a new addon panel for Visual Tests where you can run tests and view results.

![Visual Tests addon enabled](../_assets/writing-tests/vta-enable.png)

Already using the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md)? In the expanded testing widget, you’ll now see a Visual tests section:

![Expanded testing widget, showing the Visual tests section](../_assets/writing-tests/test-widget-expanded-with-vta.png)

Clicking the Run tests button at the bottom will run _all_ tests, both component and visual.

First, sign in to your Chromatic account. If you do not have an account, you can create one as part of the sign in process.

Once signed in, you will see your Chromatic account(s) and their projects. Either select one from the list or create a new one.

![Visual Tests addon project selection](../_assets/writing-tests/vta-select-project.png)

Now that you have linked your project to the addon, you can press the “Catch a UI change” button to run your first build of visual tests.

![Visual test panel showing the Catch a UI change button](../_assets/writing-tests/vta-project-linked.png)

That first build will create the baseline snapshots for your stories, which will be compared against when you run visual tests again.

## Run visual tests

After you have made a code change, there are two ways to run visual tests in Storybook.

In the expanded testing widget in the sidebar, press the run button in the Visual tests section.

![Test widget showing the Run visual tests button](../_assets/writing-tests/test-widget-expanded-with-vta.png)

Or, in the Visual tests addon panel, press the run button in the top right corner of the panel.

![Visual tests addon panel showing the Run visual tests button](../_assets/writing-tests/vta-run-from-panel.png)

Either method will send your stories to the cloud to take snapshots and detect visual changes.

## Review changes

If there are visual changes in your stories, they will be 🟡 highlighted in the sidebar. Click the story and go to the Visual Tests addon panel to see which pixels changed.

If the changes are intentional, ✅ accept them as baselines locally. If the changes aren't intentional, fix the story and rerun the tests using the rerun button.

![Visual test panel with diff](../_assets/writing-tests/vta-changes-found.png)

When you finish accepting changes as baselines in the addon, you're ready to push the code to your remote repository. This will sync baselines to the cloud for anyone who checks out your branch.

![Visual test panel with accepted baselines](../_assets/writing-tests/vta-changes-accepted.png)

## Automate with CI

The addon is designed to be used in tandem with CI. We recommend using the addon to check for changes during development and then running visual tests in CI as you get ready to merge.

Changes you accept as baselines in the addon will get auto-accepted as baselines in CI so you don’t have to review twice.

1. Add a step to your CI workflow to run Chromatic.
   - [GitHub Actions](https://chromatic.com/docs/github-actions?ref=storybook_docs)
   - [GitLab Pipelines](https://chromatic.com/docs/gitlab?ref=storybook_docs)
   - [Bitbucket Pipelines](https://chromatic.com/docs/bitbucket-pipelines?ref=storybook_docs)
   - [CircleCI](https://chromatic.com/docs/circleci?ref=storybook_docs)
   - [Travis CI](https://chromatic.com/docs/travisci?ref=storybook_docs)
   - [Jenkins](https://chromatic.com/docs/jenkins?ref=storybook_docs)
   - [Azure Pipelines](https://chromatic.com/docs/azure-pipelines?ref=storybook_docs)
   - [Custom CI provider](https://chromatic.com/docs/custom-ci-provider?ref=storybook_docs)
2. Configure your CI to include environment variables to authenticate with Chromatic (project token).

## PR checks

Once you successfully set up Chromatic in CI, your pull/merge requests will be badged with a UI Tests check. The badge notifies you of test errors or UI changes that need to be verified by your team. Make the check required in your Git provider to prevent accidental UI bugs from being merged.

![](../_assets/writing-tests/vta-prbadge-test.png)

## Configure

The addon includes configuration options covering most use cases by default. You can also fine-tune the addon configuration to match your project's requirements via the [`./chromatic.config.json`](https://www.chromatic.com/docs/visual-tests-addon/#configure) file. Below is a shortlist of addon-specific options and examples of how to use them. View the full list of [options](https://www.chromatic.com/docs/configure/#options).

| Option            | Description                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`       | Automatically configured. Sets the value for the project identifier<br />`"projectId": "Project:64cbcde96f99841e8b007d75"`             |
| `buildScriptName` | Optional. Defines the custom Storybook build script<br />`"buildScriptName": "deploy-storybook"`                                       |
| `debug`           | Optional. Output verbose debugging information to the console.<br />`"debug": true`                                                    |
| `zip`             | Optional. Recommended for large projects. Configures the addon to deploy your Storybook to Chromatic as a zip file.<br />`"zip": true` |

```json title="./chromatic.config.json"
{
  "buildScriptName": "deploy-storybook",
  "debug": true,
  "projectId": "Project:64cbcde96f99841e8b007d75",
  "zip": true
}
```

## FAQs

### What’s the difference between visual tests and snapshot tests?

[Snapshot tests](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) compare the rendered markup of every story against known baselines. This means the test compares blobs of HTML and not what the user actually sees. Which in turn, can lead to an increase in false positives as code changes don’t always yield visual changes in the component.

Visual tests compare the rendered pixels of every story against known baselines. Because you're testing the same thing your users actually experience, your tests will be richer and easier to maintain.

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests/visual-testing
---

# Snapshot tests

## Snapshot tests

Snapshot testing involves rendering a component in a given state, taking a snapshot of the rendered DOM or HTML, and then comparing it against the previous snapshot. They’re convenient to create, but can be difficult and noisy to maintain if the snapshot contains too much information. For UI components, [visual tests](https://storybook.js.org/docs/writing-tests/visual-testing.md) (easier to review) or [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md) (focused on functionality) are usually the better fit. However, there are some cases where snapshot testing may be necessary, such as ensuring an error is thrown correctly.

You can reuse your stories as the basis of snapshot tests within another test environment, like Jest or Vitest. To enable this, Storybook provides the Portable Stories API, which composes your stories with their annotations ([args](https://storybook.js.org/docs/writing-stories/args.md), [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [parameters](https://storybook.js.org/docs/writing-stories/parameters.md), etc) and produces a renderable element for your tests. Portable Stories are available for:

- [Vitest](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md)
- [Jest](https://storybook.js.org/docs/api/portable-stories/portable-stories-jest.md)
- [Playwright CT](https://storybook.js.org/docs/api/portable-stories/portable-stories-playwright.md)

Looking for snapshot testing with Storyshots? Storyshots is deprecated and no longer maintained. We recommend using the Portable Stories API instead.

Please reference the [Storyshots documentation](https://storybook.js.org/docs/8/writing-tests/snapshot-testing/storyshots-migration-guide.md) for more information on how to migrate your tests.

## Get started with Portable Stories

If you’re using Storybook Test, your project is already configured to use Portable Stories in Vitest.

If you’re not using Storybook Test or would like to test in another testing environment, please follow the relevant documentation:

- [Vitest](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md#1-apply-project-level-annotations)
- [Jest](https://storybook.js.org/docs/api/portable-stories/portable-stories-jest.md#1-apply-project-level-annotations)
- [Playwright CT](https://storybook.js.org/docs/api/portable-stories/portable-stories-playwright.md#1-apply-project-level-annotations)

## Snapshot testing a portable story

Snapshot testing a reusable story is a straightforward process of using `composeStories` from the Portable Stories API to get a renderable element, rendering that element, and then taking and comparing a snapshot.

This example renders a Button component in Vitest (by reusing one of Button’s stories) and asserts that the rendered HTML snapshot matches.

```js
// test/Button.test.js|ts — jest
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { Primary } = composeStories(stories);
test('Button snapshot', async () => {
  await Primary.run();
  expect(document.body.firstChild).toMatchSnapshot();
});
```

```js
// test/Button.test.js|ts — vitest
// @vitest-environment jsdom

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { Primary } = composeStories(stories);
test('Button snapshot', async () => {
  await Primary.run();
  expect(document.body.firstChild).toMatchSnapshot();
});
```

Once the test has run, a snapshot will be inserted or created. Then, when you run tests again and the snapshot doesn’t match, the test will fail and you will see output something like this:

```diff
FAIL  src/components/ui/Button.test.ts > Button snapshot
Error: Snapshot `Button snapshot 1` mismatched

- Expected
+ Received

  <div>
    <button
-     class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive bg-primary text-primary-foreground shadow-xs hover:bg-primary/90 h-9 px-4 py-2 has-[>svg]:px-3"
+     class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive bg-primary text-primary-foreground shadow-xs hover:bg-primary/90 h-9 px-3 py-2 has-[>svg]:px-3"
      data-slot="button"
    >
      Button
    </button>
  </div>
```

How long did it take you to find what changed? (`px-4` → `px-3`)

This is exactly why [visual tests](https://storybook.js.org/docs/writing-tests/visual-testing.md) are so much better for testing the appearance of UI components. Not only is it immediately apparent what has changed, but it also tests the actual appearance your users will see, not merely the CSS applied.

### Verifying an error is thrown

Now that we know how to do general snapshot testing, let’s apply it to a common use case: verifying that an expected error is thrown correctly.

In this example, we have a simple Button React component which for some reason accepts a prop, `doNotUseThisItWillThrowAnError`, which will (unsurprisingly) throw an error if it is used.

```tsx title="Button.tsx"
function Button(props) {
  if (props.doNotUseThisItWillThrowAnError) {
    throw new Error('I tried to tell you...');
  }

  return <button {...props} />;
}
```

We then have a story which applies that prop via `args`. It also removes the default `dev` and `test` tags to prevent the story from displaying in the Storybook sidebar and from being tested as a story (by Storybook Test), respectively.

```js title="Button.stories.js"
export const ThrowError = {
  tags: ['!dev', '!test'],
  args: {
    doNotUseThisItWillThrowAnError: true,
  },
};
```

Finally, we write a test in the test file which asserts that an error is thrown with a particular message.

```ts title="Button.test.ts"
// @vitest-environment jsdom

const { ThrowError } = composeStories(stories);

test('Button throws error', async () => {
  await expect(ThrowError.run()).rejects.toThrowError('I tried to tell you...');
});
```

This example is simplified for educational purposes. The same technique could be applied to more complex scenarios, such as a form with invalid input or a simulated network failure.

## Snapshot testing with the test-runner

If you cannot use portable stories in your project, you can still run snapshot tests using the test-runner. Follow the instructions in the [test-runner documentation](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md#run-snapshot-tests) to set up the test-runner with snapshot tests in your project.

## FAQ

### What’s the difference between snapshot tests and visual tests?

Visual tests capture images of stories and compare them against image baselines. Snapshot tests take DOM or HTML snapshots and compare them against DOM or HTML baselines. Visual tests are better suited for verifying appearance. Snapshot tests are useful for validating non-visual output and ensuring the DOM doesn’t change.

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests/snapshot-testing
---

# Test coverage

Test coverage is the practice of measuring whether existing tests fully cover your code. It marks which conditions, logic branches, functions and variables in your code are and are not being tested.

Coverage tests examine the instrumented code against a set of industry-accepted best practices. They act as the last line of QA to improve the quality of your test suite.

Each project’s coverage report will look different, but the important things to note are:

1. **The overall line/branch coverage**, which serves as a high-level health check.
2. **Specific lines/branches** that are not covered, which are potential test gaps.

When you run component tests with the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), it can generate a coverage report. The result is summarized in the testing widget, showing the percentage of statements covered by your tested stories.

![Test widget with coverage summary](../_assets/writing-tests/test-widget-coverage-summary.png)

If you cannot use the Vitest addon in your project, you can still generate code coverage using the test-runner. Follow the instructions in the [test-runner documentation](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md#generate-code-coverage) to set up the test-runner with code coverage in your project.

## Set up

Coverage is included in the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) and, when enabled, will be calculated when running component tests for your project. To enable coverage, check the coverage checkbox in the testing widget.

![Screenshot of testing widget, expanded, showing coverage toggle](../_assets/writing-tests/test-widget-coverage-enabled.png)

Before coverage can be calculated, you may need to install a support package corresponding to your [coverage provider](#coverage-provider):

```shell
# For v8
npm install --save-dev @vitest/coverage-v8

# For istanbul
npm install --save-dev @vitest/coverage-istanbul
```

```shell
# For v8
pnpm add --save-dev @vitest/coverage-v8

# For istanbul
pnpm add --save-dev @vitest/coverage-istanbul
```

```shell
# For v8
yarn add --dev @vitest/coverage-v8

# For istanbul
yarn add --dev @vitest/coverage-istanbul
```

## Usage

Because coverage is built into the Vitest addon, you can use it everywhere you run your tests.

### Storybook UI

When you enable coverage in the Storybook UI, the coverage report will be generated and summarized in the testing widget after you run your tests. You can see the percentage of statements covered by your tested stories, as well as whether the coverage meets the [watermarks](#watermarks).

Additionally, the full coverage report will be served at the `/coverage/index.html` route of your running Storybook.

![Two browser windows. The frontmost one shows the interactive coverage report generated by the Vitest addon. The background one shows the Storybook sidebar with the coverage summary visible in the testing widget.](../_assets/writing-tests/coverage-summary-and-report.png)

The report is interactive. You can click through to a component to view its source and see which parts of your code are covered by tests or not:

![Interactive coverage report generated by the Vitest addon, showing the Calendar component's reported source](../_assets/writing-tests/coverage-report-html-component.png)

It's important to understand that the coverage reported in the Storybook UI has three important limitations:

1. Coverage is calculated using the stories you've written, not the entire codebase. In other words, it will not include any other Vitest tests.
2. Coverage can only be calculated for all stories in your project, not for an individual story or a group of stories.
3. Coverage is not calculated while watch mode is activated. When coverage is enabled, enabling watch mode will disable coverage.

### CLI

Like the rest of Storybook Test, coverage is built on top of Vitest. Which means you can generate a coverage report using the [Vitest CLI](https://vitest.dev/guide/cli.html).

Assuming you run your tests with a package script like this:

```json title="package.json"
{
  "scripts": {
    "test-storybook": "vitest --project=storybook"
  }
}
```

Then you can generate a coverage report with:

```shell
npm run test-storybook -- --coverage
```

```shell
pnpm run test-storybook --coverage
```

```shell
yarn test-storybook --coverage
```

![Generated coverage report in terminal](../_assets/writing-tests/coverage-report-cli.png)

The coverage report will be saved to the [configured coverage reports directory](https://vitest.dev/config/#coverage-reportsdirectory) (`./coverage`, by default) in your project.

The above command will only calculate coverage for the stories you've written, not the entire codebase.

Because coverage is most accurate when accounting for all tests in your project, you can also run coverage for all tests in your project with:

```sh
npx vitest --coverage
```

### Editor extension

Coverage is also available through Vitest's [IDE integrations](https://vitest.dev/guide/ide.html). You can calculate and display coverage results directly in your editor.

![Screenshot of test coverage in VSCode](../_assets/writing-tests/vitest-plugin-vscode-coverage.png)

Note that this coverage will include _all_ tests in your project, not just the stories you've written.

### CI

To generate coverage reports in your CI pipeline, you can use the [CLI](#cli).

For example, here's a simplified GitHub Actions workflow that runs your tests and generates a coverage report:

```yaml title=".github/workflows/test-storybook.yml"
name: Storybook Tests
on: push
jobs:
  test:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - name: Install dependencies
        run: yarn
        # 👇 This will run all Vitest tests, including Storybook tests
      - name: Run tests
        run: yarn test --coverage
```

Why are we running all tests (`yarn test`) instead of just the Storybook tests (`yarn test-storybook`)? Because a coverage report is most accurate when accounting for all tests in your project, not just the stories you've written.

Seeing [Storybook-specific coverage](#storybook-ui) can be helpful, but in CI output, you want to see the comprehensive coverage of your project.

For more on testing in CI, see the [dedicated guide](https://storybook.js.org/docs/writing-tests/in-ci.md).

## Configuration

### Coverage provider

You can choose which provider, [v8](https://v8.dev/blog/javascript-code-coverage) (default) or [Istanbul](https://istanbul.js.org/), to use for coverage calculation by setting the `coverage.provider` option in your Vitest config:

```ts title="vitest.config.ts"

export default defineConfig({
  // ...
  test: {
    // ...
    coverage: {
      // ...
      provider: 'istanbul', // 'v8' is the default
    },
  },
});
```

### Watermarks

Both coverage providers support [watermarks](https://vitest.dev/config/#coverage-watermarks), which are threshold values for coverage. The low watermark is the minimum coverage required to pass the test, and the high watermark is the minimum coverage required to be considered good. A coverage percentage between the low and high watermarks will be considered acceptable but not ideal.

In the testing widget, the coverage summary will show the percentage of statements covered by your tested stories, as well as whether the coverage meets the watermarks. Below the low watermark, the icon will be red, between the low and high watermarks, it will be orange, and above the high watermark, it will be green.

![Screenshot of testing widget, expanded, showing coverage result](../_assets/writing-tests/test-widget-coverage-summary.png)

To configure the watermarks, you can adjust the Vitest config:

```ts title="vitest.config.ts"

export default defineConfig({
  // ...
  test: {
    // ...
    coverage: {
      // ...
      watermarks: {
        // These are the default values
        statements: [50, 80],
      },
    },
  },
});
```

### Additional configuration

You can find more configuration options for coverage in the [Vitest documentation](https://vitest.dev/config/#coverage).

When calculating coverage in the Storybook UI, the following options are always ignored:

- `enabled`
- `clean`
- `cleanOnRerun`
- `reportOnFailure`
- `reporter`
- `reportsDirectory`

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests/test-coverage
---

# Testing in CI

The [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) is great for automating your UI tests within Storybook. To have full confidence in your work, backed by tests, you need to run those automated tests in your continuous integration (CI) environment.

Thankfully, that’s quite easy!

If you cannot use the Vitest addon in your project, you can still run your stories as tests in CI using the test-runner. Follow the instructions in the [test-runner documentation](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md#set-up-ci-to-run-tests) to set up the test-runner to run in CI in your project.

## Set up Storybook tests in CI

Running Storybook tests in CI is very similar to running them via CLI on your local machine: you run the same command in a different environment.

Let’s go step-by-step to set things up.

### 1. Define `package.json` script

For convenience, define a script in your `package.json` to run the Storybook tests. This is the same command you would run locally, but it’s useful to have it in your CI workflow.

```json title="package.json"
{
  "scripts": {
    "test-storybook": "vitest --project=storybook"
  }
}
```

This script calls the `vitest` CLI command and restricts it to the “storybook” project defined in your Vitest config, which was created when you installed the Vitest addon. (If you’ve renamed the project, adjust the script above accordingly.) You can also pass any additional `vitest` [CLI options](https://vitest.dev/guide/cli.html#options) you may require.

### 2. Add a new CI workflow

Next, we’ll create a new “UI Tests” workflow to run in our CI environment. You may also adjust an existing workflow, if you prefer.

Here are some example configurations for popular CI providers:

<details>
<summary>GitHub Actions</summary>
Create a file in the root of your repo, `.github/workflow/test-ui.yml`:

```yaml title=".github/workflows/test-ui.yml"
name: UI Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      # Make sure to grab the latest version of the Playwright image
      # https://playwright.dev/docs/docker#pull-the-image
      image: mcr.microsoft.com/playwright:v1.58.2-noble
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22.12.0

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test-storybook
```

</details>

<details>
<summary>GitLab Pipelines</summary>

Create a file in the root of your repo, `.gitlab-ci.yml`:

```yaml title=".gitlab-ci.yml"
image: node:jod

stages:
  - UI_Tests

cache:
  key: $CI_COMMIT_REF_SLUG-$CI_PROJECT_DIR
  paths:
    - .npm/

before_script:
  # Install dependencies
  - npm ci
Test:
  stage: UI_Tests
  # Make sure to grab the latest version of the Playwright image
  # https://playwright.dev/docs/docker#pull-the-image
  image: mcr.microsoft.com/playwright:v1.58.2-noble
  script:
    - npm run test-storybook
```

</details>

<details>
<summary>Bitbucket Pipelines</summary>

Create a file in the root of your repo, `bitbucket-pipelines.yml`:

```yaml title="bitbucket-pipelines.yml"
image: node:jod

definitions:
  caches:
    npm: $HOME/.npm

pipelines:
  default:
    - stage:
        name: 'UI Tests'
        steps:
          - step:
              name: 'Run Tests'
              # Make sure to grab the latest version of the Playwright image
              # https://playwright.dev/docs/docker#pull-the-image
              image: mcr.microsoft.com/playwright:v1.58.2-noble
              caches:
                - npm
                - node
              script:
                # Install dependencies
                - npm ci
                - npm run test-storybook
```

</details>

<details>
<summary>Circle CI</summary>

Create a file in the root of your repo, `.circleci/config.yml`:

```yaml title=".circleci/config.yml"
version: 2.1

executors:
  ui-testing:
    docker:
      # Make sure to grab the latest version of the Playwright image
      # https://playwright.dev/docs/docker#pull-the-image
      - image: mcr.microsoft.com/playwright:v1.58.2-noble
    working_directory: ~/repo

jobs:
  Test:
    executor: ui-testing
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
            - v1-dependencies-
      # Install dependencies
      - run: npm ci
      - run: npm run test-storybook
      - save_cache:
          name: Save NPM cache
          paths:
            - ~/.npm
          key: v1-dependencies-{{ checksum "package-lock.json" }}

workflows:
  UI_Tests:
    jobs:
      - Test
```

</details>

<details>
<summary>Travis CI</summary>

Create a file in the root of your repo, `.travis.yml`:

```yaml title=".travis.yml"
language: node_js
os: linux
dist: jammy

node_js:
  - 20

before_script:
  # Install dependencies and Playwright browsers so Vitest browser mode can run story tests
  - npm ci && npm run playwright install chromium --with-deps

cache: npm

jobs:
  include:
    - stage: 'UI Tests'
      name: 'Run tests'
      script: npm run test-storybook
```

</details>

<details>
<summary>Jenkins</summary>

Create a file in the root of your repo, `JenkinsFile`:

```groovy title="JenkinsFile"
pipeline {
  agent any
  tools {nodejs "node"}

  stages {
    stage('UI Tests'){
      agent {
        docker {
          /*
           * Make sure to grab the latest version of the Playwright image
           * https://playwright.dev/docs/docker#pull-the-image
           */
          image 'mcr.microsoft.com/playwright:v1.58.2-noble'
          reuseNode true
        }
      }
      steps {
        /* Install dependencies */
        sh 'npm ci'
        sh "npm run test-storybook"
      }
    }
  }
}
```

</details>

<details>
<summary>Azure Pipelines</summary>

Create a file in the root of your repo, `azure-pipelines.yml`:

```yaml title="azure-pipelines.yml"
trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

stages:
  - stage: UI_Tests
    displayName: 'UI Tests'
    jobs:
      - job: Test
        displayName: 'Storybook tests'
        # Make sure to grab the latest version of the Playwright image
        # https://playwright.dev/docs/docker#pull-the-image
        container: mcr.microsoft.com/playwright:v1.58.2-noble
        variables:
          npm_config_cache: $(Pipeline.Workspace)/.npm
        steps:
          - task: UseNode@1
            displayName: 'Install Node.js'
            inputs:
              version: '22.12.0'
          - task: Cache@2
            displayName: 'Install and cache dependencies'
            inputs:
              key: 'npm | "$(Agent.OS)" | package-lock.json'
              restoreKeys: |
                npm | "$(Agent.OS)"
              path: $(npm_config_cache)
          - script: npm ci
            condition: ne(variables.CACHE_RESTORED, 'true')
          - task: CmdLine@2
            displayName: 'Run tests'
            inputs:
              script: npm run test-storybook
```

</details>

Storybook Test uses Playwright to render your stories by default. For the fastest experience, you should use [a machine image that has Playwright already installed](https://playwright.dev/docs/docker#pull-the-image) (as in most of the snippets above).

#### 2.1 Debug test failures

When a Storybook test fails, the failure output includes a link to the failing story. When running locally, this points to your local Storybook running at `localhost:6006`. But in CI, there is no active Storybook. Instead, you must first build and publish your Storybook, then inform the Vitest addon where your Storybook is published so that it can print useful story links.

Here's an example using GitHub Actions. The steps are similar for other CI providers, though details in the syntax or configuration may vary.

When deployments for services like Vercel, GitHub Pages, and others are performed, they follow a pattern of emitting a `deployment_status` event containing the newly generated URL under `deployment_status.environment_url`. This is the URL to the published Storybook instance.

We can pass that URL to the command using an environment variable, `SB_URL`.

```diff title=".github/workflows/test-storybook.yml"
name: Storybook Tests

+ # 👇 Update this to only run when a deployment status is emitted
+ on: deployment_status
- on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.58.2-noble
+   # 👇 Only run on successful deployments
+   if: github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success'
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22.12.0

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test-storybook
+       # 👇 Pass the Storybook URL as an environment variable
+       env:
+         SB_URL: '${{ github.event.deployment_status.environment_url }}'
```

Finally, we update the plugin configuration to use that environment variable in the [`storybookUrl` plugin option](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#storybookurl).

```ts
// vitest.config.ts — Vitest 4
export default defineConfig({
  // ...
  test: {
    // ...
    projects: [
      {
        plugins: [
          storybookTest({
            // ...
            // 👇 Use the environment variable you passed
            storybookUrl: process.env.SB_URL,
          }),
        ],
      },
    ],
  },
});
```

```ts
// vitest.workspace.ts — Vitest 3
export default defineWorkspace([
  // ...
  {
    // ...
    {
      plugins: [
        storybookTest({
        // ...
         // 👇 Use the environment variable you passed
         storybookUrl: process.env.SB_URL
        }),
      ],
    },
  },
]);
```

Now, when a test fails in CI, the printed story URL will point to the published Storybook, making debugging that failure a breeze!

#### 2.2 Calculate code coverage

For more details on code coverage, check the [full guide](https://storybook.js.org/docs/writing-tests/test-coverage.md).

You can calculate code coverage of your Storybook tests by passing the `--coverage` flag to the `vitest` command. Coverage is most useful when calculated comprehensively across all tests in your project, but you can also calculate it for just the Storybook tests.

You can either adjust the command in your `package.json` scripts:

**For all tests:**

```diff title="package.json"
{
  "scripts": {
+   "test": "vitest --coverage"
-   "test": "vitest"
  }
}
```

**For only Storybook tests:**

```diff title="package.json"
{
  "scripts": {
+   "test-storybook": "vitest --project=storybook --coverage"
-   "test-storybook": "vitest --project=storybook"
  }
}
```

Or, if you only want to calculate coverage when running tests in CI, adjust your CI configuration like so:

**For all tests:**

```diff title="CI workflow file"
+ npm run test -- --coverage
- npm run test
```

**For only Storybook tests:**

```diff title="CI workflow file"
+ npm run test-storybook -- --coverage
- npm run test-storybook
```

### 3. Run your workflow

Assuming your CI is configured to run when you push your work to a pull request, you can test your new workflow by creating a new pull request (perhaps to fix an accessibility issue found by Storybook Test).

When you do so, you should see the test result as a status check on the pull request screen. For example, in GitHub, a failing test run would look something like this:

![GitHub pull request status checks, with a failing "UI Tests / test" check](../_assets/writing-tests/test-ci-workflow-pr-status-checks.png)

Clicking on the failure will take you to the full test output, including the link to the failing story (if you've [set up the `SB_URL` environment variable](#21-debug-test-failures)).

![Test failure output in CI environment, with a link to the Storybook to debug](../_assets/writing-tests/test-ci-workflow-failure.png)

## FAQs

### How do I run other Vitest tests alongside my Storybook tests?

Some projects have other tests run via Vitest, e.g. unit tests, in addition to those defined in Storybook.

You can run these tests independently by specifying the project filter in a separate script. For example, for a Vitest project called “unit”:

```json title="package.json"
{
  "scripts": {
    "test-storybook": "vitest --project=storybook",
    "test-unit": "vitest --project=unit"
  }
}
```

Then, in your workflow, call this script alongside the Storybook one:

```yaml title=".github/workflows/test.yml"
- name: Run tests
  run: |
    npm run test-unit
    npm run test-storybook
```

You may also choose to run all tests together by omitting the `--project=storybook` filter from the `package.json` script:

```json title="package.json"
{
  "scripts": {
    "test": "vitest"
  }
}
```

The workflow would then look like:

```yaml title=".github/workflows/test.yml"
- name: Run tests
  run: |
    npm run test
```

**More testing resources**

- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
> Source: https://storybook.js.org/docs/writing-tests/in-ci
---

# Vitest addon

The Vitest addon is supported and recommended for [React](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/?renderer=react.md), [Preact](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/?renderer=preact.md), [Vue](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/?renderer=vue.md), [Svelte](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/?renderer=svelte.md), and [Web Components](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/?renderer=web-components.md) projects, which use the [Vite builder](https://storybook.js.org/docs/builders/vite.md) (or the [Next.js framework with Vite](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md)).

If you are using a different renderer (such as Angular) or the Webpack builder, you can use the [Storybook test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to test your stories.

Storybook's Vitest addon allows you to test your components directly inside Storybook. On its own, it transforms your [stories](https://storybook.js.org/docs/writing-stories.md) into component tests, which test the rendering and behavior of your components in a real browser environment. It can also calculate project [coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) provided by your stories.

If your project is using other testing addons, such as the [Visual tests addon](https://storybook.js.org/docs/writing-tests/visual-testing.md) or the [Accessibility addon](https://storybook.js.org/docs/writing-tests/accessibility-testing.md), you can run those tests alongside your component tests.

When component tests are run for a story, the status is shown in the sidebar. The sidebar can be filtered to only show failing stories, and you can press the menu button on a failing story to see debugging options.

You can also run tests in watch mode, which will automatically re-run tests when you make changes to your components or stories. To activate, press the watch mode toggle (the eye icon) in the testing widget.

## Install and set up

Before installing, make sure your project meets the following requirements:

- A Storybook framework that uses Vite (e.g. [`vue3-vite`](https://storybook.js.org/docs/get-started/frameworks/vue3-vite.md), [`react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite.md), [`preact-vite`](https://storybook.js.org/docs/get-started/frameworks/preact-vite.md), [`nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md), [`sveltekit`](https://storybook.js.org/docs/get-started/frameworks/sveltekit.md), etc.)
- Vitest ≥ 3.0
  - If you're not yet using Vitest, it will be installed and configured for you automatically
- (optional) MSW ≥ 2.0
  - If MSW is installed, it must be v2.0.0 or later to not conflict with Vitest's dependency

  

    **Using with Next.js** — The Vitest addon is supported in Next.js ≥ 14.1 projects, but you must be using the [`@storybook/nextjs-vite` framework](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md). When you run the setup command below, you will be prompted to install and use the framework if you haven't already.

  

### Automatic setup

Run the following command to install and configure the addon automatically:

```shell
npx storybook add @storybook/addon-vitest
```

```shell
pnpm exec storybook add @storybook/addon-vitest
```

```shell
yarn exec storybook add @storybook/addon-vitest
```

The [`add` command](https://storybook.js.org/docs/addons/install-addons.md#automatic-installation) will:

- Install and register the Vitest addon
- Inspect your project's Vite and Vitest setup
- Install and configure Vitest with sensible defaults if necessary
- Set up browser mode using Playwright's Chromium browser
- **Prompt you to install Playwright browser binaries** if needed

The setup is fully automated and handles all configuration for you. The full configuration options can be found in the [API section](#options), below.

If you're prompted to install Playwright browser binaries during setup, select "Yes" to install them. These are required for running tests in browser mode, which is the recommended setup for component testing.

You can install the Playwright browser binaries at any time by running [`playwright install`](https://playwright.dev/docs/browsers#install-browsers).

### Manual setup (advanced)

<details>
<summary>
Manual setup instructions (only needed if automatic setup fails)
</summary>

For some project setups, the `add` command may be unable to automate the addon and plugin setup and ask you to complete additional setup steps. Here's what to do:

1. Make sure Vite and Vitest are configured in your project.
1. Configure Vitest to use [browser mode](https://vitest.dev/guide/browser/).
1. Install the addon, `@storybook/addon-vitest`, in your project and [register it in your Storybook configuration](https://storybook.js.org/docs/addons/install-addons.md#manual-installation).
1. Adjust your Vitest configuration to include the plugin. You can use the [example configuration files](#example-configuration-files) as a guide.
   - For projects with existing Vitest tests, we recommend using a separate [test project](https://vitest.dev/guide/projects) if you're using Vitest ≥ 4.0 and a [workspace file](https://v3.vitest.dev/config/#workspace) if you're using Vitest 3.x to define separate configurations for your Storybook tests and other tests. You can run them in isolation or together, depending on your needs.

</details>

### Example configuration files

When the addon is set up automatically, it will create or adjust your Vitest configuration files for you. If you're setting up manually, you can use the following examples as a reference when configuring your project.

<details id="example-vitest-config">
  <summary>Example Vitest config file</summary>

The most simple application of the plugin is to include it in your Vitest configuration file:

```ts
// vitest.config.ts — Vitest 4

const dirname = path.dirname(fileURLToPath(import.meta.url));

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // Use `workspace` field in Vitest < 3.2
      projects: [
        {
          extends: true,
          plugins: [
            storybookTest({
              // The location of your Storybook config, main.js|ts
              configDir: path.join(dirname, '.storybook'),
              // This should match your package.json script to run Storybook
              // The --no-open flag will skip the automatic opening of a browser
              storybookScript: 'yarn storybook --no-open',
            }),
          ],
          test: {
            name: 'storybook',
            // Enable browser mode
            browser: {
              enabled: true,
              // Make sure to install Playwright
              provider: playwright({}),
              headless: true,
              instances: [{ browser: 'chromium' }],
            },
            setupFiles: ['./.storybook/vitest.setup.ts'],
          },
        },
      ],
    },
  }),
);
```

```ts
// vitest.config.ts — Vitest 3

const dirname = path.dirname(fileURLToPath(import.meta.url));

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // Use `workspace` field in Vitest < 3.2
      projects: [
        {
          extends: true,
          plugins: [
            storybookTest({
              // The location of your Storybook config, main.js|ts
              configDir: path.join(dirname, '.storybook'),
              // This should match your package.json script to run Storybook
              // The --no-open flag will skip the automatic opening of a browser
              storybookScript: 'yarn storybook --no-open',
            }),
          ],
          test: {
            name: 'storybook',
            // Enable browser mode
            browser: {
              enabled: true,
              // Make sure to install Playwright
              provider: 'playwright',
              headless: true,
              instances: [{ browser: 'chromium' }],
            },
            setupFiles: ['./.storybook/vitest.setup.ts'],
          },
        },
      ],
    },
  }),
);
```

</details>

<details id="example-vitest-workspace">
  <summary>Example Vitest workspace file (Vitest < 3.2)</summary>

If you're using a [Vitest workspace](https://v3.vitest.dev/config/#workspace), you can define a new workspace project:

```ts
// vitest.workspace.ts

const dirname = path.dirname(fileURLToPath(import.meta.url));

export default defineWorkspace([
  // This is the path to your existing Vitest config file
  './vitest.config.ts',
  {
    // This is the path to your existing Vite config file
    extends: './vite.config.ts',
    plugins: [
      storybookTest({
        // The location of your Storybook config, main.js|ts
        configDir: path.join(dirname, '.storybook'),
        // This should match your package.json script to run Storybook
        // The --ci flag will skip prompts and not open a browser
        storybookScript: 'yarn storybook --ci',
      }),
    ],
    test: {
      name: 'storybook',
      // Enable browser mode
      browser: {
        enabled: true,
        // Make sure to install Playwright
        provider: 'playwright',
        headless: true,
        instances: [{ browser: 'chromium' }],
      },
      setupFiles: ['./.storybook/vitest.setup.ts'],
    },
  },
]);
```

</details>

## Usage

There are multiple ways to run tests using the addon.

We recommend (and configure, by default) running Vitest in [browser mode](https://vitest.dev/guide/browser/), using [Playwright's](https://playwright.dev) Chromium browser. Browser mode ensures your components are tested in a real browser environment, which is more accurate than simulations like JSDom or HappyDom. This is especially important for testing components that rely on browser APIs or features.

### Storybook UI

The easiest way to run tests is through the Storybook UI. With a click, you can run multiple types of tests for all stories in your project, a group of stories, or a single story.

To run all tests for your whole project, press the Run tests button in the testing widget at the bottom of the sidebar.

![Screenshot of testing widget, expanded, with the Run tests button highlighted](../../../_assets/writing-tests/test-widget-run-all.png)

Alternatively, you can expand the testing widget to run specific types of tests individually. The sub-types listed under component tests will all run together, including when watch mode (which will automatically re-run relevant tests upon code changes) is enabled (with the eye icon).

![Screenshot of testing widget, expanded, showing test types and watch mode toggle](../../../_assets/writing-tests/test-widget-expanded.png)

If you have the [Visual tests addon](https://storybook.js.org/docs/writing-tests/visual-testing.md) installed, you'll see an option to run Visual tests alongside Component tests.

![Screenshot of testing widget, expanded, showing Visual tests](../../../_assets/writing-tests/test-widget-expanded-with-vta.png)

Other addons, such as [a11y](https://storybook.js.org/docs/writing-tests/accessibility-testing.md#run-accessibility-tests), may also provide test types that can be run from the testing widget and affect the status indicators on stories and components.

To run tests for a specific story or group of stories, press the menu button (three dots) that appears on hover of a sidebar item. You can then select the test type you want to run.

![Screenshot of story sidebar item with open menu](../../../_assets/writing-tests/context-menu.png)

After running your tests, you will now see status indicators on stories and components for their pass, fail, or error state. You can press on the menu button when hovering a story to see the test results for that story. Selecting a result in the menu will navigate you to that story and open the appropriate debugging panel. For example, if an interaction test fails, you can jump straight to the failure in the Interactions panel. That panel provides an interactive debugger for your test, allowing you to step through each simulated behavior or assertion.

The testing widget will also show you the total number of tests run, the number of tests that passed, and the number of tests that failed or errored. You can press the failure number to filter the sidebar to only those stories that failed.

### CLI

You can also run tests using the Vitest CLI. We recommend adding a script to your `package.json` to make running tests easier. Here's an example of how to do that:

```json title="package.json"
{
  "scripts": {
    "test": "vitest",
    "test-storybook": "vitest --project=storybook"
  }
}
```

In this example, we've added two scripts: `test` to run all tests in your project (you may already have this), and `test-storybook` to run only your Storybook tests. The `--project=storybook` flag tells Vitest to run the tests for the Storybook project.

Then, run this command to run your tests (in [watch mode](https://vitest.dev/guide/cli.html#vitest-watch), by default) using the Vitest CLI:

```shell
npm run test-storybook
```

```shell
pnpm run test-storybook
```

```shell
yarn test-storybook
```

#### Debugging

While the plugin does not require Storybook to run when testing, you may still want to run Storybook to debug your tests. To enable this, provide the [`storybookScript` option](#storybookscript) in the plugin configuration. When you run Vitest in watch mode, the plugin will start Storybook using this script and provide links to the story in the output on test failures. This allows you to quickly jump to the story in Storybook to debug the issue.

You can also provide a [`storybookUrl` option](#storybookurl) to the plugin configuration. When you're not using watch mode and tests fail, the plugin will provide a link to the story using this URL in the output. This is useful when [running tests in CI](#in-ci) or other environments where Storybook is not already running.

![Screenshot of test failure in the console, showing a failure with a link to the story](../../../_assets/writing-tests/vitest-plugin-test-failure.png)

### Editor extension

Transforming your stories into Vitest tests with the plugin also enables you to run and debug tests using Vitest [IDE integrations](https://vitest.dev/guide/ide.html). This allows you to run tests directly from your editor, such as VSCode and JetBrains IDE.

This screenshot shows how you can run your Vitest tests in VSCode using the [Vitest extension](https://marketplace.visualstudio.com/items?itemName=vitest.explorer). Stories are annotated with the test status, and, when a test fails, a link to the story is provided for [debugging](#debugging).

![Screenshot of test failure in VSCode, showing a failure attached to a story](../../../_assets/writing-tests/vitest-plugin-vscode.png)

### In CI

For the most part, running your Storybook tests in CI is done [via the CLI](#cli).

However, to have the test output link to your published Storybook on test failures, you need to provide the [`storybookUrl` option](#storybookurl) in the plugin configuration. Please reference the [detailed example in the Testing in CI guide](https://storybook.js.org/docs/writing-tests/in-ci.md#21-debug-test-failures).

## How it works

The Vitest addon works by using a Vitest plugin to transform your stories into [Vitest](https://vitest.dev) tests using [portable stories](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md). It also configures Vitest to run those tests in [browser mode](https://vitest.dev/guide/browser/), using Playwright's Chromium browser. Because it is built on top of Vitest, the addon requires a Vite-based Storybook framework.

Stories are tested in two ways: a smoke test to ensure it renders and, if a [play function](https://storybook.js.org/docs/writing-tests/interaction-testing.md#writing-interaction-tests) is defined, that function is run and any [assertions made](https://storybook.js.org/docs/writing-tests/interaction-testing.md#asserting-with-expect) within it are validated.

When you run tests in the [Storybook UI](#storybook-ui), the addon runs Vitest in the background and reports the results in the sidebar.

## Configuring tests

The tests run by the addon can be configured in two ways. You can toggle which test types are run and include, exclude, or skip stories from being tested.

### Toggling test types

In addition to component tests, the Vitest addon supports multiple types of tests, depending on which other addons you are using in your project. Some test types, like [visual tests](https://storybook.js.org/docs/writing-tests/visual-testing.md), are run independently. Others, like [accessibility](https://storybook.js.org/docs/writing-tests/accessibility-testing.md), must be run alongside component tests. For these dependent test types, you can toggle them on or off in the testing widget by checking or unchecking the test types you want to run.

![Screenshot of testing widget, expanded, everything is checked](../../../_assets/writing-tests/test-widget-expanded-all-enabled.png)

Note that you may not have all of the test types pictured, depending on which addons you have installed.

### Including, excluding, or skipping tests

You can use [tags](https://storybook.js.org/docs/writing-stories/tags.md) to include, exclude, or skip stories from being tested. Included stories are tested, excluded stories are not tested, and skipped stories are not tested but are counted in the test results.

By default, the plugin will run all stories with the `test` tag. You can adjust this behavior by providing the [`tags` option](#tags) in the plugin configuration. This allows you to include, exclude, or skip stories based on their tags.

In this example, we'll apply the `stable` tag to all of the Button component's stories, except for ExperimentalFeatureStory, which will have the `experimental` tag:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, etc.

const meta = {
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
} satisfies Meta<typeof Button>;

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

export const ExperimentalFeatureStory: Story = {
  //👇 For this particular story, remove the inherited `stable` tag and apply the `experimental` tag
  tags: ['!stable', 'experimental'],
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
});

export const ExperimentalFeatureStory = meta.story({
  //👇 For this particular story, remove the inherited `stable` tag and apply the `experimental` tag
  tags: ['!stable', 'experimental'],
});
```

To connect those tags to our test behavior, we can adjust the plugin configuration to exclude the `experimental` tag:

```ts
// vitest.config.ts — Vitest 4
export default defineConfig({
  // ...
  test: {
    // ...
    projects: [
      {
        plugins: [
          storybookTest({
            // ...
            tags: {
              include: ['test'],
              exclude: ['experimental'],
            },
          }),
        ],
        // ...
      },
    ],
  },
});
```

```ts
// vitest.workspace.ts — Vitest 3
export default defineWorkspace([
  // ...
  {
    // ...
    {
      plugins: [
        storybookTest({
          // ...
          tags: {
            include: ['test'],
            exclude: ['experimental'],
          },
        }),
      ],
    },
  },
]);
```

If the same tag is in both the `include` and `exclude` arrays, the `exclude` behavior takes precedence.

## Comparison to the test runner

The [test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) requires a running Storybook instance to test your stories, because it visits each one, executes the play function, and listens for results. The Vitest plugin, however, transforms your stories into tests using Vite and portable stories, so it does not need to run Storybook to test your stories. Because of this reliance on Vite, the plugin can only be used with Storybook frameworks that use Vite (and [Next.js](https://storybook.js.org/docs/get-started/frameworks/nextjs-vite.md)). The test runner, on the other hand, can be used with any Storybook framework.

| Feature                                                  | Vitest addon       | test-runner              |
| -------------------------------------------------------- | ------------------ | ------------------------ |
| **Test types**                                           |
| - [Interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md)     | ✅                 | ✅                       |
| - [Accessibility tests](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) | ✅                 | ✅                       |
| - [Visual tests](https://storybook.js.org/docs/writing-tests/visual-testing.md)               | ✅                 | ❌                       |
| - [Snapshot tests](https://storybook.js.org/docs/writing-tests/snapshot-testing.md)           | ❌                 | ✅                       |
| **Testing contexts**                                     |
| - Storybook UI                                           | ✅                 | ❌                       |
| - Editor extensions                                      | ✅                 | ❌                       |
| - CLI                                                    | ✅                 | ✅                       |
| - In CI                                                  | ✅                 | ✅                       |
| Tests run via                                            | Vitest             | Jest                     |
| Works with all Storybook frameworks                      | ❌ (requires Vite) | ✅                       |
| Runs tests in a real browser environment                 | ✅                 | ✅                       |
| Calculates code coverage                                 | ✅                 | ✅ (with addon-coverage) |
| Requires a running or published Storybook                | ❌                 | ✅                       |
| Extensible to other addons                               | ✅                 | ❌                       |

The test runner is only a CLI tool. It does not have a UI for running tests, nor does it have an editor extension. The addon, however, provides a UI in Storybook for running tests, and it enables you to run and debug tests using Vitest IDE integrations.

Additionally, the test runner ran your stories as orchestrated tests in Jest, and that orchestration came with some complexity. By comparison, this plugin transforms your stories into real tests and then runs them using Vitest, which is simpler and more configurable.

Finally, because of the simpler architecture and the use of Vitest, this plugin should be faster than the test runner for most projects. We'll do more benchmarking to quantify this in the future.

## FAQ

### What happens if Vitest itself has an error?

Sometimes tests can fail because of errors within Vitest itself. When this happens, the testing widget in the Storybook UI will alert you to the error, and you can click a link to view it in full. The error will also be logged to the console.

![Screenshot of testing widget, expanded, showing Vitest error](../../../_assets/writing-tests/test-widget-vitest-error.png)

Vitest offers [troubleshooting help for common errors](https://vitest.dev/guide/common-errors.html).

### What happens when there are different test results in multiple environments?

When you run tests with this addon, they are run as Vitest tests with whatever configuration you have set up in your project. By default, they will run in browser mode, using Playwright's Chromium browser. Sometimes, tests will fail when run in the addon (or via CLI), but then pass when viewed in the Interactions panel (or vice versa). This can happen because the tests are run in different environments, which can have different behaviors.

### How do I debug my CLI tests in Storybook?

The plugin will attempt to provide links to the story in Storybook when tests fail in CLI, for [debugging](#debugging) purposes.

If the URLs are not working when running tests in watch mode, you should check two configuration options:

- [`storybookUrl`](#storybookurl): Ensure this URL is correct and accessible. For example, the default is `http://localhost:6006`, which may not use the same port number you're using.
- [`storybookScript`](#storybookscript): Ensure this script is correctly starting Storybook.

If the URLs are not working when running tests in CI, you should ensure the Storybook is built and published before running the tests. You can then provide the URL to the published Storybook using the `storybookUrl` option. See the [In CI](#in-ci) section for an example.

### How do I ensure my tests can find assets in the public directory?

If your stories use assets in the public directory and you're not using the default public directory location (`public`), you need to adjust the Vitest configuration to include the public directory. You can do this by providing the [`publicDir` option in the Vitest configuration file](https://vitejs.dev/config/shared-options.html#publicdir).

### How do I isolate Storybook tests from others?

Some projects might contain a `test` property in their Vite configuration. Because the Vitest configuration used by this plugin extends that Vite config, the `test` properties are merged. This lack of isolation can cause issues with your Storybook tests.

To isolate your Storybook tests from other tests, you need to move the `test` property from your Vite configuration to the Vitest configuration. The Vitest config used by the plugin can then safely extend your Vite config without merging the `test` property.

Additionally, we recommend using a [test project](#example-configuration-files) if you're using Vitest ≥ 4.0, or a workspace for previous versions to define separate configurations for your Storybook tests and other tests. This ensures each can be run either in isolation or together, depending on your needs.

### Why do we recommend browser mode?

Vitest's browser mode runs your tests in a real browser (Chromium, via Playwright, in the default configuration). The alternative is a simulated browser environment, like JSDom or HappyDom, which can have differences in behavior compared to a real browser. For UI components, which can often depend on browser APIs or features, running tests in a real browser is more accurate.

For more, see [Vitest's guide on using browser mode effectively](https://vitest.dev/guide/browser/#motivation).

### How do I use WebDriver instead of Playwright?

We recommend running tests in a browser using Playwright, but you can use WebDriverIO instead. To do so, you need to adjust the [browser provider in the Vitest configuration file](https://vitest.dev/config/#browser-provider).

### How do I use a browser other than Chromium?

We recommend using Chromium, because it is most likely to best match the experience of a majority of your users. However, you can use other browsers by adjusting the [browser name in the Vitest configuration file](https://vitest.dev/config/#browser-name). Note that [Playwright and WebDriverIO support different browsers](https://vitest.dev/guide/browser/#browser-option-types).

### How do I customize a test name?

By default, the export name of a story is mapped to the test name. To create a more descriptive test description, you can provide a `name` property for the story. This allows you to include spaces, brackets, or other special characters.

```js title="Example.stories.js|ts"
export const Story = {
  name: 'custom, descriptive name',
};
```

### How do I fix the `m.createRoot is not a function` error?

This error can occur when using the addon on a project that uses a React version other than 18. To work around the issue, you can provide an alias to ensure the correct React version is used. Here's an example of how to do that in the Vitest configuration file:

```ts title="vitest.config.ts"

export default defineConfig({
  // ...
  resolve: {
    alias: {
      '@storybook/react-dom-shim': '@storybook/react-dom-shim/dist/react-16',
    },
  },
});
```

### How do I fix the `Error: Vitest failed to find the current suite` error?

If you encounter this error, it's often not a Vitest issue but rather related to how your stories are being transformed. Here are steps to troubleshoot:

1. Check the complete error logs for additional context, particularly around story transformation
2. Pay attention to Vite dependency optimization warnings (e.g., "new dependencies optimized: lodash")
3. If you see dependency optimization warnings, these can cause test-breaking reloads during execution

The most common fix is to pre-optimize your dependencies. You can do this by adding the dependencies to your Vite config's [`optimizeDeps.include`](https://vitejs.dev/config/dep-optimization-options.html#optimizedeps-include) array.

This prevents mid-test dependency optimization, which can interfere with Vitest's test suite management.

### Why do my tests fail in CI with "Failed to fetch dynamically imported module" or "Cannot connect to the iframe"?

These errors typically occur in CI environments when running a large number of tests simultaneously, which can overwhelm the available resources. They do not usually appear locally because local machines tend to have more available resources or fewer tests run in parallel.

There are two recommended approaches to fix this:

**1. Disable isolation mode**

By default, Vitest isolates each test file in its own environment. Disabling this can reduce resource consumption and prevent the errors:

```ts title="vitest.config.ts"
export default defineConfig({
  test: {
    // ...
    isolate: false,
  },
});
```

See [Vitest's `isolate` configuration](https://vitest.dev/config/isolate.html#isolate) for more details.

**2. Use sharding to split tests across multiple CI jobs**

Sharding distributes your test files across several parallel CI jobs, reducing the load on each individual runner:

```bash
# Run shard 1 of 3
vitest run --shard=1/3

# Run shard 2 of 3
vitest run --shard=2/3

# Run shard 3 of 3
vitest run --shard=3/3
```

See [Vitest's sharding guide](https://vitest.dev/guide/improving-performance.html#sharding) for more details on how to integrate this into your CI pipeline.

## API

### Exports

This addon has the following exports:

```js

```

#### `storybookTest`

Type: `function`

A [Vitest plugin](https://vitejs.dev/guide/api-plugin) that transforms your stories into tests. It accepts an [options object](#options) for configuration.

### Options

The plugin is configured using an options object. Here are the available properties:

#### `configDir`

Type: `string`

Default: `.storybook`

The directory where the Storybook configuration is located, relative to the current working directory.

If your [Storybook configuration](https://storybook.js.org/docs/configure.md) is not in the default location, you **must** specify the location here so the plugin can function correctly.

#### `storybookScript`

Type: `string`

Optional script to run Storybook. If provided, Vitest will start Storybook using this script when run in watch mode. Only runs if the Storybook in `storybookUrl` is not already available.

#### `storybookUrl`

Type: `string`

Default: `http://localhost:6006`

The URL where Storybook is hosted. This is used for internal checks and to provide a [link to the story in the test output on failures](#debugging).

#### `tags`

Type:

```ts
{
  include: string[];
  exclude: string[];
  skip: string[];
}
```

Default:

```ts
{
  include: ['test'],
  exclude: [],
  skip: [],
}
```

[Tags](https://storybook.js.org/docs/writing-stories/tags.md) to include, exclude, or skip. These tags are defined as annotations in your story, meta, or preview.

- **`include`**: Stories with these tags will be tested
- **`exclude`**: Stories with these tags will not be tested, and will not be counted in the test results
- **`skip`**: Stories with these tags will not be tested, and will be counted in the test results

#### `disableAddonDocs`

Type: `boolean`

Default: `true`

Whether to disable addon docs MDX parsing while running tests.

When either the preview config or stories import mdx files, they are mocked as normally they are not needed for tests.
You might set `disableAddonDocs` to `false` only in case your stories actually need to read and parse MDX files as part of rendering your components.

**More testing resources**

- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
> Source: https://storybook.js.org/docs/writing-tests/integrations/vitest-addon
---

# Test runner

The test runner has been superseded by the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), which offers the same functionality, powered by the faster and more modern [Vitest](https://vitest.dev/) browser mode. It also enables the full Storybook Test experience, allowing you to run interaction, accessibility, and visual tests from your Storybook app.

If you are using a Vite-powered Storybook framework, we recommend using the Vitest addon instead of the test runner.

Storybook test runner turns all of your stories into executable tests. It is powered by [Jest](https://jestjs.io/) and [Playwright](https://playwright.dev/).

- For those [without a play function](https://storybook.js.org/docs/writing-stories.md): it verifies whether the story renders without any errors.
- For those [with a play function](https://storybook.js.org/docs/writing-stories/play-function.md): it also checks for errors in the play function and that all assertions passed.

These tests run in a live browser and can be executed via the [command line](#cli-options) or your [CI server](#set-up-ci-to-run-tests).

## Setup

The test-runner is a standalone, framework-agnostic utility that runs parallel to your Storybook. You will need to take some additional steps to set it up properly. Detailed below is our recommendation to configure and execute it.

Run the following command to install it.

```shell
npm install @storybook/test-runner --save-dev
```

```shell
pnpm add --save-dev @storybook/test-runner
```

```shell
yarn add --dev @storybook/test-runner
```

Update your `package.json` scripts and enable the test runner.

```json title="package.json"
{
  "scripts": {
    "test-storybook": "test-storybook"
  }
}
```

Start your Storybook with:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

Storybook's test runner requires either a locally running Storybook instance or a published Storybook to run all the existing tests.

Finally, open a new terminal window and run the test-runner with:

```shell
npm run test-storybook
```

```shell
pnpm run test-storybook
```

```shell
yarn test-storybook
```

## Configure

Test runner offers zero-config support for Storybook. However, you can run `test-storybook --eject` for more fine-grained control. It generates a `test-runner-jest.config.js` file at the root of your project, which you can modify. Additionally, you can extend the generated configuration file and provide [testEnvironmentOptions](https://github.com/playwright-community/jest-playwright#configuration) as the test runner also uses [jest-playwright](https://github.com/playwright-community/jest-playwright) under the hood.

### CLI Options

The test-runner is powered by [Jest](https://jestjs.io/) and accepts a subset of its [CLI options](https://jestjs.io/docs/cli) (for example, `--watch`, `--maxWorkers`).
If you're already using any of those flags in your project, you should be able to migrate them into Storybook's test-runner without any issues. Listed below are all the available flags and examples of using them.

| Options                         | Description                                                                                                                                                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--help`                        | Output usage information <br />`test-storybook --help`                                                                                                                                                    |
| `-s`, `--index-json`            | Run in index json mode. Automatically detected (requires a compatible Storybook) <br />`test-storybook --index-json`                                                                                      |
| `--no-index-json`               | Disables index json mode <br />`test-storybook --no-index-json`                                                                                                                                           |
| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from <br />`test-storybook -c .storybook`                                                                                                                |
| `--watch`                       | Run in watch mode <br />`test-storybook --watch`                                                                                                                                                          |
| `--watchAll`                    | Watch files for changes and rerun all tests when something changes.<br />`test-storybook --watchAll`                                                                                                      |
| `--coverage`                    | Runs [coverage tests](#generate-code-coverage) on your stories and components <br /> `test-storybook --coverage`                                                                                          |
| `--coverageDirectory`           | Directory where to write coverage report output <br />`test-storybook --coverage --coverageDirectory coverage/ui/storybook`                                                                               |
| `--url`                         | Define the URL to run tests in. Useful for custom Storybook URLs <br />`test-storybook --url http://the-storybook-url-here.com`                                                                           |
| `--browsers`                    | Define browsers to run tests in. One or multiple of: chromium, firefox, webkit <br />`test-storybook --browsers firefox chromium`                                                                         |
| `--maxWorkers [amount]`         | Specifies the maximum number of workers the worker-pool will spawn for running tests <br />`test-storybook --maxWorkers=2`                                                                                |
| `--testTimeout [amount]`        | Defines the maximum time in milliseconds that a test can run before it is automatically marked as failed. Useful for long-running tests <br /> `test-storybook --testTimeout=60000`                       |
| `--no-cache`                    | Disable the cache <br />`test-storybook --no-cache`                                                                                                                                                       |
| `--clearCache`                  | Deletes the Jest cache directory and then exits without running tests <br />`test-storybook --clearCache`                                                                                                 |
| `--verbose`                     | Display individual test results with the test suite hierarchy <br />`test-storybook --verbose`                                                                                                            |
| `-u`, `--updateSnapshot`        | Use this flag to re-record every snapshot that fails during this test run <br />`test-storybook -u`                                                                                                       |
| `--eject`                       | Creates a local configuration file to override defaults of the test-runner <br />`test-storybook --eject`                                                                                                 |
| `--json`                        | Prints the test results in JSON. This mode will send all other test output and user messages to stderr. <br />`test-storybook --json`                                                                     |
| `--outputFile`                  | Write test results to a file when the --json option is also specified. <br />`test-storybook --json --outputFile results.json`                                                                            |
| `--junit`                       | Indicates that test information should be reported in a junit file. <br />`test-storybook --**junit**`                                                                                                    |
| `--ci`                          | Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest to be run with `--updateSnapshot`. <br />`test-storybook --ci`                            |
| `--shard [index/count]`         | Requires CI. Splits the test suite execution into multiple machines <br /> `test-storybook --shard=1/8`                                                                                                   |
| `--failOnConsole`               | Makes tests fail on browser console errors<br />`test-storybook --failOnConsole`                                                                                                                          |
| `--includeTags`                 | Experimental feature <br />Defines a subset of stories to be tested if they match the enabled [tags](#experimental-filter-tests). <br />`test-storybook --includeTags="test-only, pages"`                 |
| `--excludeTags`                 | Experimental feature <br />Prevents stories from being tested if they match the provided [tags](#experimental-filter-tests). <br />`test-storybook --excludeTags="no-tests, tokens"`                      |
| `--skipTags`                    | Experimental feature <br />Configures the test runner to skip running tests for stories that match the provided [tags](#experimental-filter-tests). <br />`test-storybook --skipTags="skip-test, layout"` |

```shell
npm run test-storybook -- --watch
```

```shell
pnpm run test-storybook --watch
```

```shell
yarn test-storybook --watch
```

### Run tests against a deployed Storybook

By default, the test-runner assumes that you're running it against a locally served Storybook on port `6006`. If you want to define a target URL to run against deployed Storybooks, you can use the `--url` flag:

```shell
npm run test-storybook -- --url https://the-storybook-url-here.com
```

```shell
pnpm run test-storybook  --url https://the-storybook-url-here.com
```

```shell
yarn test-storybook --url https://the-storybook-url-here.com
```

Alternatively, you can set the `TARGET_URL` environment variable and run the test-runner:

```sh
TARGET_URL=https://the-storybook-url-here.com yarn test-storybook
```

## Run accessibility tests

When you have the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) installed, you can run accessibility tests alongside your interaction tests, using the test-runner.

For more details, including configuration options, see the [Accessibility testing documentation](https://storybook.js.org/docs/writing-tests/accessibility-testing.md).

## Run snapshot tests

[Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) is a helpful tool for verifying that edge cases like errors are handled correctly. It can also be used to verify that the rendered output of a component is consistent across different test runs.

### Set up

To enable snapshot testing with the test-runner, you'll need to take additional steps to set it up properly.

Add a new [configuration file](#test-hook-api) inside your Storybook directory with the following inside:

```ts
// .storybook/test-runner.ts

const config: TestRunnerConfig = {
  async postVisit(page, context) {
    // the #storybook-root element wraps the story. In Storybook 6.x, the selector is #root
    const elementHandler = await page.$('#storybook-root');
    const innerHTML = await elementHandler.innerHTML();
    expect(innerHTML).toMatchSnapshot();
  },
};

export default config;
```

The `postVisit` hook allows you to extend the test runner's default configuration. Read more about them [here](#test-hook-api).

When you execute the test-runner (for example, with `yarn test-storybook`), it will run through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the `__snapshots__` directory.

### Configure

Out of the box, the test-runner provides an inbuilt snapshot testing configuration covering most use cases. You can also fine-tune the configuration to fit your needs via `test-storybook --eject` or by creating a `test-runner-jest.config.js` file at the root of your project.

#### Override the default snapshot directory

The test-runner uses a specific naming convention and path for the generated snapshot files by default. If you need to customize the snapshot directory, you can define a custom snapshot resolver to specify the directory where the snapshots are stored.

Create a `snapshot-resolver.js` file to implement a custom snapshot resolver:

```js
// ./snapshot-resolver.js

export default {
  resolveSnapshotPath: (testPath) => {
    const fileName = path.basename(testPath);
    const fileNameWithoutExtension = fileName.replace(/\.[^/.]+$/, '');
    // Defines the file extension for the snapshot file
    const modifiedFileName = `${fileNameWithoutExtension}.snap`;

    // Configure Jest to generate snapshot files using the following convention (./src/test/__snapshots__/Button.stories.snap)
    return path.join('./src/test/__snapshots__', modifiedFileName);
  },
  resolveTestPath: (snapshotFilePath, snapshotExtension) =>
    path.basename(snapshotFilePath, snapshotExtension),
  testPathForConsistencyCheck: 'example',
};
```

Update the `test-runner-jest.config.js` file and enable the `snapshotResolver` option to use the custom snapshot resolver:

```js
// ./test-runner-jest.config.js

const defaultConfig = getJestConfig();

const config = {
  // The default Jest configuration comes from @storybook/test-runner
  ...defaultConfig,
  snapshotResolver: './snapshot-resolver.js',
};

export default config;
```

When the test-runner is executed, it will cycle through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the custom directory you specified.

#### Customize snapshot serialization

By default, the test-runner uses [`jest-serializer-html`](https://github.com/algolia/jest-serializer-html) to serialize HTML snapshots. This may cause issues if you use specific CSS-in-JS libraries like [Emotion](https://emotion.sh/docs/introduction), Angular's `ng` attributes, or similar libraries that generate hash-based identifiers for CSS classes. If you need to customize the serialization of your snapshots, you can define a custom snapshot serializer to specify how the snapshots are serialized.

Create a `snapshot-serializer.js` file to implement a custom snapshot serializer:

```js
// ./snapshot-serializer.js
// The jest-serializer-html package is available as a dependency of the test-runner
const jestSerializerHtml = require('jest-serializer-html');

const DYNAMIC_ID_PATTERN = /"react-aria-\d+(\.\d+)?"/g;

module.exports = {
  /*
   * The test-runner calls the serialize function when the test reaches the expect(SomeHTMLElement).toMatchSnapshot().
   * It will replace all dynamic IDs with a static ID so that the snapshot is consistent.
   * For instance, from <label id="react-aria970235672-:rl:" for="react-aria970235672-:rk:">Favorite color</label> to <label id="react-mocked_id" for="react-mocked_id">Favorite color</label>
   */
  serialize(val) {
    const withFixedIds = val.replace(DYNAMIC_ID_PATTERN, 'mocked_id');
    return jestSerializerHtml.print(withFixedIds);
  },
  test(val) {
    return jestSerializerHtml.test(val);
  },
};
```

Update the `test-runner-jest.config.js` file and enable the `snapshotSerializers` option to use the custom snapshot resolver:

```js
// ./test-runner-jest.config.js

const defaultConfig = getJestConfig();

const config = {
  ...defaultConfig,
  snapshotSerializers: [
    // Sets up the custom serializer to preprocess the HTML before it's passed onto the test-runner
    './snapshot-serializer.js',
    ...defaultConfig.snapshotSerializers,
  ],
};

export default config;
```

When the test-runner executes your tests, it will introspect the resulting HTML, replacing the dynamically generated attributes with the static ones provided by the regular expression in the custom serializer file before snapshotting the component. This ensures that the snapshots are consistent across different test runs.

## Generate code coverage

Storybook also provides a [coverage addon](https://storybook.js.org/addons/@storybook/addon-coverage). It is powered by [Istanbul](https://istanbul.js.org/), which allows out-of-the-box code instrumentation for the most commonly used frameworks and builders in the JavaScript ecosystem.

### Set up

Engineered to work alongside modern testing tools (e.g., [Playwright](https://playwright.dev/)), the coverage addon automatically instruments your code and generates code coverage data. For an optimal experience, we recommend using the test-runner alongside the coverage addon to run your tests.

Run the following command to install the addon.

```shell
npx storybook@latest add @storybook/addon-coverage
```

```shell
pnpm dlx storybook@latest add @storybook/addon-coverage
```

```shell
yarn dlx storybook@latest add @storybook/addon-coverage
```

The CLI's [`add`](https://storybook.js.org/docs/api/cli-options.md#add) command automates the addon's installation and setup. To install it manually, see our [documentation](https://storybook.js.org/docs/addons/install-addons.md#manual-installation) on how to install addons.

Start your Storybook with:

```shell
npm run storybook
```

```shell
pnpm run storybook
```

```shell
yarn storybook
```

Finally, open a new terminal window and run the test-runner with:

```shell
npm run test-storybook -- --coverage
```

```shell
pnpm run test-storybook --coverage
```

```shell
yarn test-storybook --coverage
```

![Coverage test output](../../_assets/writing-tests/test-runner-coverage-result.png)

### Configure

By default, the [`@storybook/addon-coverage`](https://storybook.js.org/addons/@storybook/addon-coverage) offers zero-config support for Storybook and instruments your code via [`istanbul-lib-instrument`](https://www.npmjs.com/package/istanbul-lib-instrument) for [Webpack](https://webpack.js.org/), or [`vite-plugin-istanbul`](https://github.com/iFaxity/vite-plugin-istanbul) for [Vite](https://vitejs.dev/). However, you can extend your Storybook configuration file (i.e., `.storybook/main.js|ts`) and provide additional options to the addon. Listed below are the available options divided by builder and examples of how to use them.

```ts
// .storybook/main.ts — CSF 3
// For Vite support add the following import
// import type { AddonOptionsVite } from '@storybook/addon-coverage';

// Replace your-framework with the framework and builder you are using (e.g., react-webpack5, vue3-webpack5)

const coverageConfig: AddonOptionsWebpack = {
  istanbul: {
    include: ['**/stories/**'],
    exclude: ['**/exampleDirectory/**'],
  },
};

const config: StorybookConfig = {
  stories: [],
  addons: [
    // Other Storybook addons
    {
      name: '@storybook/addon-coverage',
      options: coverageConfig,
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

// For Vite support add the following import
// import type { AddonOptionsVite } from '@storybook/addon-coverage';

const coverageConfig: AddonOptionsWebpack = {
  istanbul: {
    include: ['**/stories/**'],
    exclude: ['**/exampleDirectory/**'],
  },
};

export default defineMain({
  stories: [],
  addons: [
    // Other Storybook addons
    {
      name: '@storybook/addon-coverage',
      options: coverageConfig,
    },
  ],
});
```

<details>
<summary>Vite options</summary>

| Options                | Description                                                                                                                                                                                                                                         | Type                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `checkProd`            | Configures the plugin to skip instrumentation in production environments<br />`options: { istanbul: { checkProd: true,}}`                                                                                                                           | `boolean`                   |
| `cwd`                  | Configures the working directory for the coverage tests.<br />Defaults to `process.cwd()`<br />`options: { istanbul: { cwd: process.cwd(),}}`                                                                                                       | `string`                    |
| `cypress`              | Replaces the `VITE_COVERAGE` environment variable with `CYPRESS_COVERAGE`.<br />Requires Cypress's [code coverage](https://docs.cypress.io/guides/tooling/code-coverage)<br />`options: { istanbul: { cypress: true,}}`                             | `boolean`                   |
| `exclude`              | Overrides the [default exclude list](https://github.com/storybookjs/addon-coverage/blob/main/src/constants.ts) with the provided list of files or directories to exclude from coverage<br />`options: { istanbul: { exclude: ['**/stories/**'],}}`  | `Array<String>` or `string` |
| `extension`            | Extends the [default extension list](https://github.com/storybookjs/addon-coverage/blob/main/src/constants.ts) with the provided list of file extensions to include in coverage<br />`options: { istanbul: { extension: ['.js', '.cjs', '.mjs'],}}` | `Array<String>` or `string` |
| `forceBuildInstrument` | Configures the plugin to add instrumentation in build mode <br />`options: { istanbul: { forceBuildInstrument: true,}}`                                                                                                                             | `boolean`                   |
| `include`              | Select the files to collect coverage<br />`options: { istanbul: { include: ['**/stories/**'],}}`                                                                                                                                                    | `Array<String>` or `string` |
| `nycrcPath`            | Defines the relative path for the existing nyc [configuration file](https://github.com/istanbuljs/nyc?tab=readme-ov-file#configuration-files)<br />`options: { istanbul: { nycrcPath: '../nyc.config.js',}}`                                        | `string`                    |
| `requireEnv`           | Overrides the `VITE_COVERAGE` environment variable's value by granting access to the `env` variables<br />`options: { istanbul: { requireEnv: true,}}`                                                                                              | `boolean`                   |

</details>

<details>
<summary>Webpack 5 options</summary>

| Options                | Description                                                                                                                                                                                                                                         | Type                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `autoWrap`             | Provides support for top-level return statements by wrapping the program code in a function<br />`options: { istanbul: { autoWrap: true,}}`                                                                                                         | `boolean`                   |
| `compact`              | Condenses the output of the instrumented code. Useful for debugging<br />`options: { istanbul: { compact: false,}}`                                                                                                                                 | `boolean`                   |
| `coverageVariable`     | Defines the global variable name that Istanbul will use to store coverage results<br />`options: { istanbul: { coverageVariable: '__coverage__',}}`                                                                                                 | `string`                    |
| `cwd`                  | Configures the working directory for the coverage tests.<br />Defaults to `process.cwd()`<br />`options: { istanbul: { cwd: process.cwd(),}}`                                                                                                       | `string`                    |
| `debug`                | Enables the debug mode for additional logging information during the instrumentation process<br />`options: { istanbul: { debug: true,}}`                                                                                                           | `boolean`                   |
| `esModules`            | Enables support for ES Module syntax<br />`options: { istanbul: { esModules: true,}}`                                                                                                                                                               | `boolean`                   |
| `exclude`              | Overrides the [default exclude list](https://github.com/storybookjs/addon-coverage/blob/main/src/constants.ts) with the provided list of files or directories to exclude from coverage<br />`options: { istanbul: { exclude: ['**/stories/**'],}}`  | `Array<String>` or `string` |
| `extension`            | Extends the [default extension list](https://github.com/storybookjs/addon-coverage/blob/main/src/constants.ts) with the provided list of file extensions to include in coverage<br />`options: { istanbul: { extension: ['.js', '.cjs', '.mjs'],}}` | `Array<String>` or `string` |
| `include`              | Select the files to collect coverage<br />`options: { istanbul: { include: ['**/stories/**'],}}`                                                                                                                                                    | `Array<String>` or `string` |
| `nycrcPath`            | Defines the relative path for the existing nyc [configuration file](https://github.com/istanbuljs/nyc?tab=readme-ov-file#configuration-files)<br />`options: { istanbul: { nycrcPath: '../nyc.config.js',}}`                                        | `string`                    |
| `preserveComments`     | Includes comments in the instrumented code<br />`options: { istanbul: { preserveComments: true,}}`                                                                                                                                                  | `boolean`                   |
| `produceSourceMap`     | Configures Instanbul to generate a source map for the instrumented code<br />`options: { istanbul: { produceSourceMap: true,}}`                                                                                                                     | `boolean`                   |
| `sourceMapUrlCallback` | Defines a callback function invoked with the filename and the source map URL when a source map is generated<br />`options: { istanbul: { sourceMapUrlCallback: (filename, url) => {},}}`                                                            | `function`                  |

</details>

### What about other coverage reporting tools?

Out of the box, code coverage tests work seamlessly with Storybook's test-runner and the [`@storybook/addon-coverage`](https://storybook.js.org/addons/@storybook/addon-coverage). However, that doesn't mean you can't use additional reporting tools (e.g., [Codecov](https://about.codecov.io/)). For instance, if you're working with [LCOV](https://wiki.documentfoundation.org/Development/Lcov), you can use the generated output (in `coverage/storybook/coverage-storybook.json`) and create your own report with:

```shell
npx nyc report --reporter=lcov -t coverage/storybook --report-dir coverage/storybook
```

## Set up CI to run tests

You can also configure the test-runner to run tests on a CI environment. Documented below are some recipes to help you get started.

### Run against deployed Storybooks via Github Actions deployment

If you're publishing your Storybook with services such as [Vercel](https://vercel.com/) or [Netlify](https://docs.netlify.com/site-deploys/notifications/#github-commit-statuses), they emit a `deployment_status` event in GitHub Actions. You can use it and set the `deployment_status.target_url` as the `TARGET_URL` environment variable. Here's how:

```yml
// .github/workflows/storybook-tests.yml — yml
name: Storybook Tests

on: deployment_status

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    if: github.event.deployment_status.state == 'success'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
      - name: Install dependencies
        run: yarn
      - name: Install Playwright
        run: npx playwright install --with-deps
      - name: Run Storybook tests
        run: yarn test-storybook
        env:
          TARGET_URL: '${{ github.event.deployment_status.target_url }}'
```

The published Storybook must be publicly available for this example to work. We recommend running the test server using the recipe [below](#run-against-non-deployed-storybooks) if it requires authentication.

### Run against non-deployed Storybooks

You can use your CI provider (for example, [GitHub Actions](https://github.com/features/actions), [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/), [CircleCI](https://circleci.com/)) to build and run the test runner against your built Storybook. Here's a recipe that relies on third-party libraries, that is to say, [concurrently](https://www.npmjs.com/package/concurrently), [http-server](https://www.npmjs.com/package/http-server), and [wait-on](https://www.npmjs.com/package/wait-on) to build Storybook and run tests with the test-runner.

```yml
// .github/workflows/storybook-tests.yml — yml
name: 'Storybook Tests'

on: push

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
      - name: Install dependencies
        run: yarn
      - name: Install Playwright
        run: npx playwright install --with-deps
      - name: Build Storybook
        run: yarn build-storybook --quiet
      - name: Serve Storybook and run tests
        run: |
          npx concurrently -k -s first -n "SB,TEST" -c "magenta,blue" \
            "npx http-server storybook-static --port 6006 --silent" \
            "npx wait-on tcp:127.0.0.1:6006 && yarn test-storybook"
```

By default, Storybook outputs the [build](https://storybook.js.org/docs/sharing/publish-storybook.md#build-storybook-as-a-static-web-application) to the `storybook-static` directory. If you're using a different build directory, you'll need to adjust the recipe accordingly.

## Advanced configuration

### Test hook API

The test-runner renders a story and executes its [play function](https://storybook.js.org/docs/writing-stories/play-function.md) if one exists. However, certain behaviors are impossible to achieve via the play function, which executes in the browser. For example, if you want the test-runner to take visual snapshots for you, this is possible via Playwright/Jest but must be executed in Node.

The test-runner exports test hooks that can be overridden globally to enable use cases like visual or DOM snapshots. These hooks give you access to the test lifecycle _before_ and _after_ the story is rendered.
Listed below are the available hooks and an overview of how to use them.

| Hook        | Description                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `prepare`   | Prepares the browser for tests<br />`async prepare({ page, browserContext, testRunnerConfig }) {}`               |
| `setup`     | Executes once before all the tests run<br />`setup() {}`                                                         |
| `preVisit`  | Executes before a story is initially visited and rendered in the browser<br />`async preVisit(page, context) {}` |
| `postVisit` | Executes after the story is visited and fully rendered<br />`async postVisit(page, context) {}`                  |

These test hooks are experimental and may be subject to breaking changes. We encourage you to test as much as possible within the story's [play function](https://storybook.js.org/docs/writing-stories/play-function.md).

To enable the hooks API, you'll need to add a new configuration file inside your Storybook directory and set them up as follows:

```ts
// .storybook/test-runner.ts

const config: TestRunnerConfig = {
  // Hook that is executed before the test runner starts running tests
  setup() {
    // Add your configuration here.
  },
  /* Hook to execute before a story is initially visited before being rendered in the browser.
   * The page argument is the Playwright's page object for the story.
   * The context argument is a Storybook object containing the story's id, title, and name.
   */
  async preVisit(page, context) {
    // Add your configuration here.
  },
  /* Hook to execute after a story is visited and fully rendered.
   * The page argument is the Playwright's page object for the story
   * The context argument is a Storybook object containing the story's id, title, and name.
   */
  async postVisit(page, context) {
    // Add your configuration here.
  },
};

export default config;
```

Except for the `setup` function, all other functions run asynchronously. Both `preVisit` and `postVisit` functions include two additional arguments, a [Playwright page](https://playwright.dev/docs/pages) and a context object which contains the `id`, `title`, and the `name` of the story.

When the test-runner executes, your existing tests will go through the following lifecycle:

- The `setup` function is executed before all the tests run.
- The context object is generated containing the required information.
- Playwright navigates to the story's page.
- The `preVisit` function is executed.
- The story is rendered, and any existing `play` functions are executed.
- The `postVisit` function is executed.

### (Experimental) Filter tests

When you run the test-runner on Storybook, it tests every story by default. However, if you want to filter the tests, you can use the `tags` configuration option. Storybook originally introduced this feature to generate [automatic documentation](https://storybook.js.org/docs/writing-docs/autodocs.md) for stories. But it can be further extended to configure the test-runner to run tests according to the provided tags using a similar configuration option or via CLI flags (e.g., `--includeTags`, `--excludeTags`, `--skipTags`), only available with the latest stable release (`0.15` or higher). Listed below are the available options and an overview of how to use them.

| Option    | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| `exclude` | Prevents stories if they match the provided tags from being tested.           |
| `include` | Defines a subset of stories only to be tested if they match the enabled tags. |
| `skip`    | Skips testing on stories if they match the provided tags.                     |

```ts
// .storybook/test-runner.ts

const config: TestRunnerConfig = {
  tags: {
    include: ['test-only', 'pages'],
    exclude: ['no-tests', 'tokens'],
    skip: ['skip-test', 'layout'],
  },
};

export default config;
```

Running tests with the CLI flags takes precedence over the options provided in the configuration file and will override the available options in the configuration file.

#### Disabling tests

If you want to prevent specific stories from being tested by the test-runner, you can configure your story with a custom tag, enable it to the test-runner configuration file or run the test-runner with the `--excludeTags` [CLI](#cli-options) flag and exclude them from testing. This is helpful when you want to exclude stories that are not yet ready for testing or are irrelevant to your tests. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework

const meta = {
  component: MyComponent,
  //👇 Provides the `no-tests` tag to all stories in this file
  tags: ['no-tests'],
} satisfies Meta<typeof MyComponent>;

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

export const ExcludeStory: Story = {
  //👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
  tags: ['no-tests'],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
  //👇 Provides the `no-tests` tag to all stories in this file
  tags: ['no-tests'],
});

export const ExcludeStory = meta.story({
  //👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
  tags: ['no-tests'],
});
```

#### Run tests for a subset of stories

To allow the test-runner only to run tests on a specific story or subset of stories, you can configure the story with a custom tag, enable it in the test-runner configuration file or run the test-runner with the `--includeTags` [CLI](#cli-options) flag and include them in your tests. For example, if you wanted to run tests based on the `test-only` tag, you can adjust your configuration as follows:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework

const meta = {
  component: MyComponent,
  //👇 Provides the `test-only` tag to all stories in this file
  tags: ['test-only'],
} satisfies Meta<typeof MyComponent>;

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

export const IncludeStory: Story = {
  //👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
  tags: ['test-only'],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
  //👇 Provides the `test-only` tag to all stories in this file
  tags: ['test-only'],
});

export const IncludeStory = meta.story({
  //👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
  tags: ['test-only'],
});
```

Applying tags for the component's stories should either be done at the component level (using `meta`) or at the story level. Importing tags across stories is not supported in Storybook and won't work as intended.

#### Skip tests

If you want to skip running tests on a particular story or subset of stories, you can configure your story with a custom tag, enable it in the test-runner configuration file, or run the test-runner with the `--skipTags` [CLI](#cli-options) flag. Running tests with this option will cause the test-runner to ignore and flag them accordingly in the test results, indicating that the tests are temporarily disabled. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework

const meta = {
  component: MyComponent,
  //👇 Provides the `skip-test` tag to all stories in this file
  tags: ['skip-test'],
} satisfies Meta<typeof MyComponent>;

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

export const SkipStory: Story = {
  //👇 Adds the `skip-test` tag to this story to allow it to be skipped in the tests when enabled in the test-runner configuration
  tags: ['skip-test'],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
  //👇 Provides the `skip-test` tag to all stories in this file
  tags: ['skip-test'],
});

export const SkipStory = meta.story({
  //👇 Adds the `skip-test` tag to this story to allow it to be skipped in the tests when enabled in the test-runner configuration
  tags: ['skip-test'],
});
```

### Authentication for deployed Storybooks

If you use a secure hosting provider that requires authentication to host your Storybook, you may need to set HTTP headers. This is mainly because of how the test runner checks the status of the instance and the index of its stories through fetch requests and Playwright. To do this, you can modify the test-runner configuration file to include the `getHttpHeaders` function. This function takes the URL of the fetch calls and page visits as input and returns an object containing the headers that need to be set.

```ts
// .storybook/test-runner.ts

const config: TestRunnerConfig = {
  getHttpHeaders: async (url) => {
    const token = url.includes('prod') ? 'prod-token' : 'dev-token';
    return {
      Authorization: `Bearer ${token}`,
    };
  },
};

export default config;
```

### Helpers

The test-runner exports a few helpers that can be used to make your tests more readable and maintainable by accessing Storybook's internals (e.g., `args`, `parameters`). Listed below are the available helpers and an overview of how to use them.

```ts
// .storybook/test-runner.ts

const config: TestRunnerConfig = {
  // Hook that is executed before the test runner starts running tests
  setup() {
    // Add your configuration here.
  },
  /* Hook to execute before a story is initially visited before being rendered in the browser.
   * The page argument is the Playwright's page object for the story.
   * The context argument is a Storybook object containing the story's id, title, and name.
   */
  async preVisit(page, context) {
    // Add your configuration here.
  },
  /* Hook to execute after a story is visited and fully rendered.
   * The page argument is the Playwright's page object for the story
   * The context argument is a Storybook object containing the story's id, title, and name.
   */
  async postVisit(page, context) {
    // Get the entire context of a story, including parameters, args, argTypes, etc.
    const storyContext = await getStoryContext(page, context);

    // This utility function is designed for image snapshot testing. It will wait for the page to be fully loaded, including all the async items (e.g., images, fonts, etc.).
    await waitForPageReady(page);

    // Add your configuration here.
  },
};

export default config;
```

#### Accessing story information with the test-runner

If you need to access information about the story, such as its parameters, the test-runner includes a helper function named `getStoryContext` that you can use to retrieve it. You can then use it to customize your tests further as needed. For example, if you need to configure Playwright's page [viewport size](https://playwright.dev/docs/api/class-page#page-set-viewport-size) to use the viewport size defined in the story's parameters, you can do so as follows:

```ts
// .storybook/test-runner.ts

const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };

const config: TestRunnerConfig = {
  async preVisit(page, story) {
    // Accesses the story's parameters and retrieves the viewport used to render it
    const context = await getStoryContext(page, story);
    const viewportName = context.parameters?.viewport?.defaultViewport;
    const viewportParameter = MINIMAL_VIEWPORTS[viewportName];

    if (viewportParameter) {
      const viewportSize = Object.entries(viewportParameter.styles).reduce(
        (acc, [screen, size]) => ({
          ...acc,
          // Converts the viewport size from percentages to numbers
          [screen]: parseInt(size),
        }),
        {},
      );
      // Configures the Playwright page to use the viewport size
      page.setViewportSize(viewportSize);
    } else {
      page.setViewportSize(DEFAULT_VIEWPORT_SIZE);
    }
  },
};

export default config;
```

#### Working with assets

If you're running a specific set of tests (e.g., image snapshot testing), the test-runner provides a helper function named `waitForPageReady` that you can use to ensure the page is fully loaded and ready before running the test. For example:

```ts
// .storybook/test-runner.ts

const customSnapshotsDir = `${process.cwd()}/__snapshots__`;

const config: TestRunnerConfig = {
  setup() {
    expect.extend({ toMatchImageSnapshot });
  },
  async postVisit(page, context) {
    // Awaits for the page to be loaded and available including assets (e.g., fonts)
    await waitForPageReady(page);

    // Generates a snapshot file based on the story identifier
    const image = await page.screenshot();
    expect(image).toMatchImageSnapshot({
      customSnapshotsDir,
      customSnapshotIdentifier: context.id,
    });
  },
};

export default config;
```

### Index.json mode

The test-runner transforms your story files into tests when testing a local Storybook. For a remote Storybook, it uses the Storybook's [index.json](https://storybook.js.org/docs/configure.md) (formerly `stories.json`) file (a static index of all the stories) to run the tests.

#### Why?

Suppose you run into a situation where the local and remote Storybooks appear out of sync, or you might not even have access to the code. In that case, the `index.json` file is guaranteed to be the most accurate representation of the deployed Storybook you are testing. To test a local Storybook using this feature, use the `--index-json` flag as follows:

```shell
npm run test-storybook -- --index-json
```

```shell
pnpm run test-storybook --index-json
```

```shell
yarn test-storybook --index-json
```

The `index.json` mode is not compatible with the watch mode.

If you need to disable it, use the `--no-index-json` flag:

```shell
npm run test-storybook -- --no-index-json
```

```shell
pnpm run test-storybook --no-index-json
```

```shell
yarn test-storybook --no-index-json
```

#### How do I check if my Storybook has a `index.json` file?

Index.json mode requires a `index.json` file. Open a browser window and navigate to your deployed Storybook instance (for example, `https://your-storybook-url-here.com/index.json`). You should see a JSON file that starts with a `"v": 3` key, immediately followed by another key called "stories", which contains a map of story IDs to JSON objects. If that is the case, your Storybook supports [index.json mode](https://storybook.js.org/docs/configure.md).

## What's the difference between Chromatic and Test runner?

The test-runner is a generic testing tool that can run locally or on CI and be configured or extended to run all kinds of tests.

[Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) is a cloud-based service that runs [visual](https://storybook.js.org/docs/writing-tests/visual-testing.md) and [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md) (and soon [accessibility tests](https://storybook.js.org/docs/writing-tests/accessibility-testing.md)) without setting up the test runner. It also syncs with your git provider and manages access control for private projects.

However, you might want to pair the test runner and Chromatic in some cases.

- Use it locally and Chromatic on your CI.
- Use Chromatic for visual and component tests and run other custom tests using the test runner.

## Troubleshooting

### The test runner seems flaky and keeps timing out

If your tests time out with the following message:

```shell
Timeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout
```

It might be that Playwright couldn't handle testing the number of stories you have in your project. Perhaps you have a large number of stories, or your CI environment has a really low RAM configuration. In such cases, you should limit the number of workers that run in parallel by adjusting your command as follows:

```json title="package.json"
{
  "scripts": {
    "test-storybook:ci": "yarn test-storybook --maxWorkers=2"
  }
}
```

### The error output in the CLI is too short

By default, the test runner truncates error outputs at 1000 characters, and you can check the full output directly in Storybook in the browser. However, if you want to change that limit, you can do so by setting the `DEBUG_PRINT_LIMIT` environment variable to a number of your choosing, for example, `DEBUG_PRINT_LIMIT=5000 yarn test-storybook`.

### Run the test runner in other CI environments

As the test runner is based on Playwright, you might need to use specific docker images or other configurations depending on your CI setup. In that case, you can refer to the [Playwright CI docs](https://playwright.dev/docs/ci) for more information.

### Tests filtered by tags are incorrectly executed

If you've enabled filtering tests with tags and provided similar tags to the `include` and `exclude` lists, the test-runner will execute the tests based on the `exclude` list and ignore the `include` list. To avoid this, make sure the tags provided to the `include` and `exclude` lists differ.

### The test runner doesn't support Yarn PnP out of the box

If you've enabled the test-runner in a project running on a newer version of Yarn with Plug'n'Play (PnP) enabled, the test-runner might not work as expected and may generate the following error when running tests:

```shell
PlaywrightError: jest-playwright-preset: Cannot find playwright package to use chromium
```

This is due to the test-runner using the community-maintained package [jest-playwright-preset](https://github.com/playwright-community/jest-playwright) that still needs to support this feature. To solve this, you can either switch the [`nodeLinker`](https://yarnpkg.com/features/linkers) setting to `node-modules` or install Playwright as a direct dependency in your project, followed by adding the browser binaries via the [`install`](https://playwright.dev/docs/browsers#install-browsers) command.

### Run test coverage in other frameworks

If you intend on running coverage tests in frameworks with special files like Vue 3 or Svelte, you'll need to adjust your configuration and enable the required file extensions. For example, if you're using Vue, you'll need to add the following to your nyc configuration file (i.e., `.nycrc.json` or `nyc.config.js`):

```js
// .nyc.config.js — JavaScript configuration
export default {
  // Other configuration options
  extension: ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.vue'],
};
```

```json
// .nycrc.json — JSON configuration
{
  "extension": [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".vue"]
}
```

### The coverage addon doesn't support optimized builds

If you generated a production build optimized for performance with the [`--test`](https://storybook.js.org/docs/sharing/publish-storybook.md#customizing-the-build-for-performance) flag, and you're using the coverage addon to run tests against your Storybook, you may run into a situation where the coverage addon doesn't instrument your code. This is due to how the flag works, as it removes addons that have an impact on performance (e.g., [`Docs`](https://storybook.js.org/docs/writing-docs.md), [coverage addon](https://storybook.js.org/addons/@storybook/addon-coverage)). To resolve this issue, you'll need to adjust your Storybook configuration file (i.e., `.storybook/main.js|ts`) and include the [`disabledAddons`](https://storybook.js.org/docs/api/main-config/main-config-build.md#testdisabledaddons) option to allow the addon to run tests at the expense of a slower build.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-docs', '@storybook/addon-vitest', '@storybook/addon-coverage'],
  build: {
    test: {
      disabledAddons: ['@storybook/addon-docs'],
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-docs', '@storybook/addon-vitest', '@storybook/addon-coverage'],
  build: {
    test: {
      disabledAddons: ['@storybook/addon-docs'],
    },
  },
});
```

### The coverage addon doesn't support instrumented code

As the [coverage addon](https://storybook.js.org/addons/@storybook/addon-coverage) is based on Webpack5 loaders and Vite plugins for code instrumentation, frameworks that don't rely upon these libraries (e.g., Angular configured with Webpack), will require additional configuration to enable code instrumentation. In that case, you can refer to the following [repository](https://github.com/yannbf/storybook-coverage-recipes) for more information.

**More testing resources**

- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
> Source: https://storybook.js.org/docs/writing-tests/integrations/test-runner
---

# Stories in unit tests

Teams test a variety of UI characteristics using different tools. Each tool requires you to replicate the same component state over and over. That’s a maintenance headache. Ideally, you’d set up your tests similarly and reuse that across tools.

Storybook enables you to isolate a component and capture its use cases in a `*.stories.js|ts` file. Stories are standard JavaScript modules that are cross-compatible with the whole JavaScript ecosystem.

Stories are a practical starting point for UI testing. Import stories into tools like [Jest](https://jestjs.io/), [Testing Library](https://testing-library.com/), [Vitest](https://vitest.dev/) and [Playwright](https://playwright.dev/), to save time and maintenance work.

## Write a test with Testing Library

[Testing Library](https://testing-library.com/) is a suite of helper libraries for browser-based component tests. With [Component Story Format](https://storybook.js.org/docs/api/csf.md), your stories are reusable with Testing Library. Each named export (story) is renderable within your testing setup. For example, if you were working on a login component and wanted to test the invalid credentials scenario, here's how you could write your test:

Storybook provides a [`composeStories`](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md#composestories) utility that helps convert stories from a test file into renderable elements that can be reused in your Node tests with JSDOM. It also allows you to apply other Storybook features that you have enabled your project (e.g., [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [args](https://storybook.js.org/docs/writing-stories/args.md)) into your tests, enabling you to reuse your stories in your testing environment of choice (e.g., [Jest](https://jestjs.io/), [Vitest](https://vitest.dev/)), ensuring your tests are always in sync with your stories without having to rewrite them. This is what we refer to as portable stories in Storybook.

```ts
// Form.test.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { InvalidForm } = composeStories(stories);

test('Checks if the form is valid', async () => {
  const user = userEvent.setup();

  // Renders the composed story
  await InvalidForm.run();

  const buttonElement = screen.getByRole('button', {
    name: 'Submit',
  });

  await user.click(buttonElement);

  const isFormValid = screen.getByLabelText('invalid-form');
  expect(isFormValid).toBeInTheDocument();
});
```

These examples use Testing Library's `screen` queries because the composed stories run inside your unit test renderer. In a story's `play` function, prefer the provided `canvas` queries so interactions stay scoped to the rendered story.

You **must** [configure your test environment to use portable stories](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md#1-apply-project-level-annotations) to ensure your stories are composed with all aspects of your Storybook configuration, such as [decorators](https://storybook.js.org/docs/writing-stories/decorators.md).

Once the test runs, it loads the story and renders it. [Testing Library](https://testing-library.com/) then emulates the user's behavior and checks if the component state has been updated.

### Override story properties

By default, the `setProjectAnnotations` function injects into your existing tests any global configuration you've defined in your Storybook instance (i.e., parameters, decorators in the `preview.*` file). Nevertheless, this may cause unforeseen side effects for tests that are not intended to use these global configurations. For example, you may want to always test a story in a particular locale (via `globalTypes`) or configure a story to apply specific `decorators` or `parameters`.

To avoid this, you can override the global configurations by extending either the `composeStory` or `composeStories` functions to provide test-specific configurations. For example:

```js
// Form.test.js|ts — compose-stories
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const { ValidForm } = composeStories(stories, {
  decorators: [
    // Decorators defined here will be added to all composed stories from this function
  ],
  globalTypes: {
    // Override globals for all composed stories from this function
  },
  parameters: {
    // Override parameters for all composed stories from this function
  },
});
```

```js
// Form.test.js|ts — compose-story
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const ValidForm = composeStory(ValidFormStory, Meta, {
  decorators: [
    // Decorators defined here will be added to this story
  ],
  globalTypes: {
    // Override globals for this story
  },
  parameters: {
    // Override parameters for this story
  },
});
```

## Run tests on a single story

You can use the [`composeStory`](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md#composestory) function to allow your tests to run on a single story. However, if you're relying on this method, we recommend that you supply the story metadata (i.e., the [default export](https://storybook.js.org/docs/writing-stories/index.md#default-export)) to the `composeStory` function. This ensures that your tests can accurately determine the correct information about the story. For example:

```ts
// Form.test.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const ValidForm = composeStory(ValidFormStory, Meta);

test('Validates form', async () => {
  const user = userEvent.setup();

  await ValidForm.run();

  const buttonElement = screen.getByRole('button', {
    name: 'Submit',
  });

  await user.click(buttonElement);

  const isFormValid = screen.getByLabelText('invalid-form');
  expect(isFormValid).not.toBeInTheDocument();
});
```

## Combine stories into a single test

If you intend to test multiple stories in a single test, use the [`composeStories`](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest.md#composestories) function. It will process every component story you've specified, including any [`args`](https://storybook.js.org/docs/writing-stories/args.md) or [`decorators`](https://storybook.js.org/docs/writing-stories/decorators.md) you've defined. For example:

```ts
// Form.test.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { InvalidForm, ValidForm } = composeStories(FormStories);

test('Tests invalid form state', async () => {
  const user = userEvent.setup();

  await InvalidForm.run();

  const buttonElement = screen.getByRole('button', {
    name: 'Submit',
  });

  await user.click(buttonElement);

  const isFormValid = screen.getByLabelText('invalid-form');
  expect(isFormValid).toBeInTheDocument();
});

test('Tests filled form', async () => {
  const user = userEvent.setup();

  await ValidForm.run();

  const buttonElement = screen.getByRole('button', {
    name: 'Submit',
  });

  await user.click(buttonElement);

  const isFormValid = screen.getByLabelText('invalid-form');
  expect(isFormValid).not.toBeInTheDocument();
});
```

## Troubleshooting

### Run tests in other frameworks

Storybook provides community-led addons for other frameworks like [Vue 2](https://storybook.js.org/addons/@storybook/testing-vue) and [Angular](https://storybook.js.org/addons/@storybook/testing-angular). However, these addons still lack support for the latest stable Storybook release. If you're interested in helping out, we recommend reaching out to the maintainers using the default communication channels (GitHub and [Discord server](https://discord.com/channels/486522875931656193/839297503446695956)).

### The args are not being passed to the test

The components returned by `composeStories` or `composeStory` not only can be rendered as React components but also come with the combined properties from the story, meta, and global configuration. This means that if you want to access args or parameters, for instance, you can do so:

```ts
// Button.test.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { Primary } = composeStories(stories);

test('reuses args from composed story', () => {
  render();

  const buttonElement = screen.getByRole('button');
  // Testing against values coming from the story itself! No need for duplication
  expect(buttonElement.textContent).toEqual(Primary.args.label);
});
```

### Next.js Vite cannot find the module

If you are seeing error messages like `Cannot find module 'sb-original/image-context'` ensure you have included `storybookNextJsPlugin`.

```ts
// vitest.config.ts

export default defineConfig({
  // only necessary when not using @storybook/addon-vitest, otherwise the plugin is loaded automatically
  plugins: [storybookNextJsPlugin()],
});
```

**More testing resources**

- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
- [End-to-end testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) for simulating real user scenarios
> Source: https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests
---

# Stories in end-to-end tests

Storybook seamlessly integrates with additional testing frameworks like [Cypress](https://www.cypress.io/) and [Playwright](https://playwright.dev/) to provide a comprehensive testing solution. By leveraging the Component Story Format (CSF), developers can write test cases that simulate user interactions and verify the behavior of individual components within the Storybook environment. This approach enables developers to thoroughly test their components' functionality, responsiveness, and visual appearance across different scenarios, resulting in more robust and reliable applications.

## With Cypress

[Cypress](https://www.cypress.io/) is an end-to-end testing framework. It enables you to test a complete instance of your application by simulating user behavior. With Component Story Format, your stories are reusable with Cypress. Each named export (in other words, a story) is renderable within your testing setup.

An example of an end-to-end test with Cypress and Storybook is testing a login component for the correct inputs. For example, if you had the following story:

```ts
// LoginForm.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: LoginForm,
} satisfies Meta<typeof LoginForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const EmptyForm: Story = {};

export const FilledForm: Story = {
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};
```

```ts
// LoginForm.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: LoginForm,
});

export const EmptyForm = meta.story();

export const FilledForm = meta.story({
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
});
```

The play function contains small snippets of code that run after the story renders. It allows you to sequence interactions in stories.

With Cypress, you could write the following test:

```js
// /cypress/integration/Login.spec.js
/// <reference types="cypress" />

describe('Login Form', () => {
  it('Should contain valid login information', () => {
    cy.visit('/iframe.html?id=components-login-form--example');
    cy.get('#login-form').within(() => {
      cy.log('**enter the email**');
      cy.get('#email').should('have.value', 'email@provider.com');
      cy.log('**enter password**');
      cy.get('#password').should('have.value', 'a-random-password');
    });
  });
});
```

When Cypress runs your test, it loads Storybook's isolated iframe and checks if the inputs match the test values.

## With Playwright

[Playwright](https://playwright.dev/) is a browser automation tool and end-to-end testing framework from Microsoft. It offers cross-browser automation, mobile testing with device emulation, and headless testing. With Component Story Format, your stories are reusable with Playwright. Each named export (in other words, a story) is renderable within your testing setup.

A real-life scenario of user flow testing with Playwright would be how to test a login form for validity. For example, if you had the following story already created:

```ts
// LoginForm.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: LoginForm,
} satisfies Meta<typeof LoginForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const EmptyForm: Story = {};

export const FilledForm: Story = {
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};
```

```ts
// LoginForm.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: LoginForm,
});

export const EmptyForm = meta.story();

export const FilledForm = meta.story({
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');

    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');

    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));

    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
});
```

The play function contains small snippets of code that run after the story renders. It allows you to sequence interactions in stories.

With Playwright, you can write a test to check if the inputs are filled and match the story:

```js
// tests/login-form/login.spec.js

test('Login Form inputs', async ({ page }) => {
  await page.goto('http://localhost:6006/iframe.html?id=components-login-form--example');
  const email = await page.inputValue('#email');
  const password = await page.inputValue('#password');
  await expect(email).toBe('email@provider.com');
  await expect(password).toBe('a-random-password');
});
```

Once you execute Playwright, it opens a new browser window, loads Storybook's isolated iframe, asserts if the inputs contain the specified values, and displays the test results in the terminal.

**More testing resources**

- [Interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for user behavior simulation
- [Accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) for accessibility
- [Visual testing](https://storybook.js.org/docs/writing-tests/visual-testing.md) for appearance
- [Snapshot testing](https://storybook.js.org/docs/writing-tests/snapshot-testing.md) for rendering errors and warnings
- [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md) for measuring code coverage
- [CI](https://storybook.js.org/docs/writing-tests/in-ci.md) for running tests in your CI/CD pipeline
- [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) for running tests in Storybook
- [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md) to automate test execution
- [Unit testing](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md) for functionality
> Source: https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests
---

# How to document components

When you write component stories during development, you also create basic documentation to revisit later.

Storybook gives you tools to expand this essential documentation with prose and layout that feature your components and stories prominently. That allows you to create UI library usage guidelines, design system sites, and more.

![Docs page](../_assets/writing-docs/docs-completed.png)

If you're including Storybook in your project for the [first time](https://storybook.js.org/docs/get-started/install.md), we provide you with a [documentation page](https://storybook.js.org/docs/writing-docs/autodocs.md) ("Autodocs" for short), positioned near your stories. It's a baseline template automatically generated, listing your existing stories and relevant metadata.

Additionally, you can customize this template if needed or create free-form pages for each component using [MDX](https://storybook.js.org/docs/writing-docs/mdx.md). In both cases, you’ll use Doc Blocks as the building blocks to create full-featured documentation.

Docs is autoconfigured to work out of the box in most use cases. In some cases, you may need or want to tweak the configuration. Read more about it [here](https://storybook.js.org/addons/@storybook/addon-docs).
> Source: https://storybook.js.org/docs/writing-docs
---

# Automatic documentation and Storybook

Storybook Autodocs is a powerful tool that can help you quickly generate comprehensive documentation for your UI components. By leveraging Autodocs, you're transforming your stories into living documentation which can be further extended with [MDX](https://storybook.js.org/docs/writing-docs/mdx.md) and [Doc Blocks](https://storybook.js.org/docs/writing-docs/doc-blocks.md) to provide a clear and concise understanding of your components' functionality.

Storybook infers the relevant metadata (e.g., [`args`](https://storybook.js.org/docs/writing-stories/args.md), [`argTypes`](https://storybook.js.org/docs/api/arg-types.md), [`parameters`](https://storybook.js.org/docs/writing-stories/parameters.md)) and automatically generates a documentation page with this information positioned at the root-level of your component tree in the sidebar.

![Storybook autodocs](../_assets/writing-docs/autodocs.png)

## Set up automated documentation

Autodocs is configured through [tags](https://storybook.js.org/docs/writing-stories/tags.md). If a [CSF](https://storybook.js.org/docs/api/csf.md) file contains at least one story tagged with `autodocs`, then a documentation page will be generated for that component.

To enable automatic documentation for all stories in a project, add it to `tags` in your `.storybook/preview.jsx|tsx` file:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  //👇 Enables auto-generated documentation for all stories
  tags: ['autodocs'],
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  //👇 Enables auto-generated documentation for all stories
  tags: ['autodocs'],
});
```

You can also enable it at the component (or story) level:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  //👇 Enables auto-generated documentation for this component and includes all stories in this file
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;
export default meta;
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  //👇 Enables auto-generated documentation for this component and includes all stories in this file
  tags: ['autodocs'],
});
```

You can disable auto docs for a particular component by [removing the tag](https://storybook.js.org/docs/writing-stories/tags.md#removing-tags):

```ts
// Page.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Page,
  // 👇 Disable auto-generated documentation for this component
  tags: ['!autodocs'],
} satisfies Meta<typeof Page>;
export default meta;
```

```ts
// Page.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Page,
  // 👇 Disable auto-generated documentation for this component
  tags: ['!autodocs'],
});
```

Similarly, you can exclude a particular story from the auto docs page, by removing the tag:

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  //👇 Enables auto-generated documentation for this component and includes all stories in this file
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

export const UndocumentedStory: Story = {
  // 👇 Removes this story from auto-generated documentation
  tags: ['!autodocs'],
};
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  //👇 Enables auto-generated documentation for this component and includes all stories in this file
  tags: ['autodocs'],
});

export const UndocumentedStory = meta.story({
  // 👇 Removes this story from auto-generated documentation
  tags: ['!autodocs'],
});
```

### Configure

In addition to enabling the feature with `tags`, you can extend your Storybook configuration file (i.e., `.storybook/main.js|ts|cjs`) and provide additional options to control how documentation gets created. Listed below are the available options and examples of how to use them.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-docs'],
  docs: {
    //👇 See the table below for the list of supported options
    defaultName: 'Documentation',
    docsMode: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-docs'],
  docs: {
    //👇 See the table below for the list of supported options
    defaultName: 'Documentation',
    docsMode: true,
  },
});
```

| Option                                                               | Description                                                                                                                    |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [`defaultName`](https://storybook.js.org/docs/api/main-config/main-config-docs.md#defaultname) | Renames the auto-generated documentation page<br /> Default: `docs: { defaultName: 'Docs' }`                                   |
| [`docsMode`](https://storybook.js.org/docs/api/main-config/main-config-docs.md#docsmode)       | Toggles the documentation mode, which only shows documentation pages in the sidebar<br /> Default: `docs: { docsMode: false }` |

### Write a custom template

To replace the default documentation template used by Storybook, you can extend your UI configuration file (i.e., `.storybook/preview.jsx|tsx`) and introduce a `docs` [parameter](https://storybook.js.org/docs/writing-docs/doc-blocks.md#customizing-the-automatic-docs-page). This parameter accepts a `page` function that returns a React component, which you can use to generate the required template. For example:

```tsx
// .storybook/preview.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

  Title,
  Subtitle,
  Description,
  Primary,
  Controls,
  Stories,
} from '@storybook/addon-docs/blocks';

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    docs: {
      page: () => (
        <>
          
          
          
          
          
          
        </>
      ),
    },
  },
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

  Controls,
  Description,
  Primary,
  Stories,
  Subtitle,
  Title,
} from '@storybook/addon-docs/blocks';

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    docs: {
      page: () => (
        <>
          
          
          
          
          
          
        </>
      ),
    },
  },
});
```

Internally, Storybook uses a similar implementation to generate the default template. See the Doc Blocks [API reference](https://storybook.js.org/docs/writing-docs/doc-blocks.md#available-blocks) to learn more about how Doc Blocks work.

Going over the code snippet in more detail. When Storybook starts up, it will override the default template with the custom one composed of the following:

1. A header with the component's metadata retrieved by the `Title`, `Subtitle`, and `Description` Doc Blocks.
2. The first story defined in the file via the `Primary` Doc Block with a handy set of UI controls to zoom in and out of the component.
3. An interactive table with all the relevant [`args`](https://storybook.js.org/docs/writing-stories/args.md) and [`argTypes`](https://storybook.js.org/docs/api/arg-types.md) defined in the story via the `Controls` Doc Block.
4. A overview of the remaining stories via the `Stories` Doc Block.

#### With MDX

You can also use MDX to generate the documentation template. This is useful in non-React projects where JSX-handling is not configured. Normally, when you create an MDX file in your project, it is treated as normal documentation. To indicate that an MDX file is a documentation template, supply the `isTemplate` property to its [`Meta`](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md) Doc Block. For example:

```mdx
// DocumentationTemplate.mdx

# Default implementation

## Inputs

The component accepts the following inputs (props):

---

## Additional variations

Listed below are additional variations of the component.

```

Then you can use it in your `.storybook/preview.jsx|tsx` or an individual story file by importing it:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview = {
  parameters: {
    docs: {
      page: DocumentationTemplate,
    },
  },
} satisfies Preview;

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      page: DocumentationTemplate,
    },
  },
});
```

If you only need to override the documentation page for a single component, we recommend creating an MDX file and referencing it directly via the `` Doc Block.

### Generate a table of contents

Storybook's auto-generated documentation pages can be quite long and difficult to navigate. To help with this, you can enable the table of contents feature to provide a quick overview of the documentation page and allow users to jump to a specific section. To enable it, extend your Storybook UI configuration file (i.e., `.storybook/preview.jsx|tsx`) and provide a `docs` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) with a `toc` property.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      toc: true, // 👈 Enables the table of contents
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      toc: true, // 👈 Enables the table of contents
    },
  },
});
```

### Configure the table of contents

By default, the table of contents on the documentation page will only show the `h3` headings that are automatically generated. However, if you want to customize the table of contents, you can add more parameters to the `toc` property. The following options and examples of how to use them are available.

| Option                | Description                                                                                                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentsSelector`    | Defines the container's CSS selector for search for the headings <br /> `toc: { contentsSelector: '.sbdocs-content' }`                                                                                           |
| `disable`             | Hides the table of contents for the documentation pages <br /> `toc: { disable: true }`                                                                                                                          |
| `headingSelector`     | Defines the list of headings to feature in the table of contents <br /> `toc: { headingSelector: 'h1, h2, h3' }`                                                                                                 |
| `ignoreSelector`      | Configures the table of contents to ignore specific headings or stories. By default, the table of contents will ignore all content placed within Story blocks <br /> `toc: { ignoreSelector: '.docs-story h2' }` |
| `title`               | Defines a title caption for the table of contents. <br />Accepts one of: `string`, `null`, React element <br /> `toc: { title: 'Table of Contents' }`                                                            |
| `unsafeTocbotOptions` | Provides additional [`TocBot`](https://tscanlin.github.io/tocbot/) configuration options <br /> `toc: { unsafeTocbotOptions: { orderedList: true } }`                                                            |

The `contentsSelector`, `headingSelector`, and `ignoreSelector` properties allow additional customization. For more information on using them, see the [`Tocbot` documentation](https://tscanlin.github.io/tocbot/).

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      toc: {
        contentsSelector: '.sbdocs-content',
        headingSelector: 'h1, h2, h3',
        ignoreSelector: '#primary',
        title: 'Table of Contents',
        disable: false,
        unsafeTocbotOptions: {
          orderedList: false,
        },
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      toc: {
        contentsSelector: '.sbdocs-content',
        headingSelector: 'h1, h2, h3',
        ignoreSelector: '#primary',
        title: 'Table of Contents',
        disable: false,
        unsafeTocbotOptions: {
          orderedList: false,
        },
      },
    },
  },
});
```

#### Component-level configuration

If you want to customize the table of contents for a specific story, you can include a `toc` property in the story's meta (or default export) and provide the required [configuration](#configure-the-table-of-contents). For example, if you need to hide the table of contents for a specific story, adjust your story as follows:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: MyComponent,
  tags: ['autodocs'],
  parameters: {
    docs: {
      toc: {
        disable: true, // 👈 Disables the table of contents
      },
    },
  },
} satisfies Meta<typeof MyComponent>;

export default meta;
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
  tags: ['autodocs'],
  parameters: {
    docs: {
      toc: {
        disable: true, // 👈 Disables the table of contents
      },
    },
  },
});
```

### Customize component documentation

Creating automated documentation with Storybook's Autodocs provides you with the starting point to build a sustainable documentation pattern. Nevertheless, it may not be suited for every case, and you may want to extend it and provide additional information. We recommend combining [MDX](https://storybook.js.org/docs/writing-docs/mdx.md) alongside Storybook's [Doc Blocks](https://storybook.js.org/docs/writing-docs/doc-blocks.md) for such cases to author your documentation.

## Advanced configuration

### Documenting multiple components

Sometimes it's helpful to document multiple components together. For example, a component library’s ButtonGroup and Button components might not make sense without one another.

Autodocs allows you to document your "main" component, defined by the `component` property, as well as one or more `subcomponents` related to it.

```tsx
// List.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: List,
  subcomponents: { ListItem }, //👈 Adds the ListItem component as a subcomponent
} satisfies Meta<typeof List>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Empty: Story = {};

export const OneItem: Story = {
  render: (args) => (
    
      
    
  ),
};
```

```tsx
// List.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: List,
  subcomponents: { ListItem }, //👈 Adds the ListItem component as a subcomponent
});

export const Empty = meta.story();

export const OneItem = meta.story({
  render: (args) => (
    
      
    
  ),
});
```

![Subcomponents in ArgTypes doc block](../_assets/writing-stories/doc-block-arg-types-subcomponents-for-list.png)

The main component and its subcomponents will show up in a tabbed version of the [`ArgTypes` doc block](https://storybook.js.org/docs/writing-docs/doc-blocks.md#argtypes). The tab titles will correspond to the keys of the `subcomponents` object.

If you want to organize your documentation differently for component groups, we recommend [using MDX](https://storybook.js.org/docs/writing-docs/mdx.md). It gives you complete control over how your components are displayed and supports any configuration.

### Customize the Docs Container

The Docs Container is the component that wraps up the documentation page. It's responsible for rendering the documentation page in Storybook's UI. You can customize it by creating your own component and updating your Storybook UI configuration file (i.e., `.storybook/preview.jsx|tsx`) to reference it.

```tsx
// .storybook/preview.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const ExampleContainer = ({ children, ...props }) => {
  return {children};
};

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

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const ExampleContainer = ({ children, ...props }) => {
  return {children};
};

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    docs: {
      container: ExampleContainer,
    },
  },
});
```

### Override the default theme

By default, Storybook provides two themes for the UI: `light` and `dark`. If you need to customize the theme used by the documentation to match the existing one, you can update your Storybook UI configuration file (i.e., `.storybook/preview.jsx|tsx`) and apply it.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    docs: {
      theme: ensure(themes.dark), // The replacement theme to use
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    docs: {
      theme: ensure(themes.dark), // The replacement theme to use
    },
  },
});
```

### Working with custom MDX components

Out of the box, Storybook has a set of components that you can use to customize your documentation page. If you're working with a design system or component library and wish to add them to your documentation page, you can override the `MDXProvider` component inherited from `@mdx-js/react` with your own. However, there's a caveat to this, the component replacement will only have an impact if you're writing documentation using Markdown syntax (e.g., `#` for headings). Native HTML elements, such as `<h1>`, will not be replaced with your custom implementation.

```tsx
// .storybook/preview.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

export const MyDocsContainer = (props) => (
  
    
  
);

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

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export const MyDocsContainer = (props) => (
  
    
  
);

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    docs: {
      container: MyDocsContainer,
    },
  },
});
```

This is not a Storybook issue but a detail of how MDX works. From their [migration guide](https://mdxjs.com/migrating/v2/#update-mdx-content):

“We now ‘sandbox’ components, for lack of a better name. It means that when you pass a component for h1, it does get used for `# hi` but not for `<h1>hi</h1>`”

### Addon options

The docs addon accepts options to customize the behavior of the documentation page. You can add them to your Storybook UI configuration file (i.e., `.storybook/main.js|ts`), as part of registering the addon. The following options are available:

| Option             | Description                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `csfPluginOptions` | Provides additional configuration for Storybook's CSF plugin. Can be disabled with `null`.                                                                     |
| `mdxPluginOptions` | Provides additional configuration options and plugin configuration for [MDX documentation](https://storybook.js.org/docs/writing-docs/mdx.md#markdown-tables-arent-rendering-correctly). |

This example demonstrates how to apply these options.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        csfPluginOptions: null,
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [],
          },
        },
      },
    },
  ],
};

export default config;
```

```js
// .storybook/main.js — CSF 3
export default {
  // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        csfPluginOptions: null,
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [],
          },
        },
      },
    },
  ],
};
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        csfPluginOptions: null,
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [],
          },
        },
      },
    },
  ],
});
```

## Troubleshooting

### The table of contents doesn't render as expected

When using Autodocs's table of contents, you may encounter situations where it appears differently than expected. To help you resolve these problems, we have compiled a list of possible scenarios that may cause issues.

#### With simple documentation pages

If you have a documentation page with only one matching heading and create a table of contents for it, the table of contents will not be hidden by default. A potential solution for this issue would be to add a second heading or turn it off entirely.

#### With small screens

If the screen width is less than 1200px, the table of contents will be hidden by default. Currently, there's no built-in solution for this issue that doesn't impact the documentation page's style compatibility.

#### With MDX

If you're writing [unattached documentation](https://storybook.js.org/docs/writing-docs/mdx.md#writing-unattached-documentation) using MDX, you cannot customize the table of contents primarily due to the lack of support for defining parameters based on the current implementation. As a result, the table of contents will always revert to the default [configuration](#configure-the-table-of-contents) provided globally.

### The auto-generated documentation is not showing up in a monorepo setup

Out of the box, Storybook's Autodocs feature is built to generate documentation for your stories automatically. Nevertheless, if you're working with a monorepo setup (e.g., [`Yarn Workspaces`](https://yarnpkg.com/features/workspaces), [`pnpm Workspaces`](https://pnpm.io/workspaces)), you may run into issues where part of the documentation may not be generated for you. To help you troubleshoot those issues, we've prepared some recommendations that might help you.

Update your import statements to reference the component directly instead of the package's root. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// ❌ Don't use the package's index file to import the component.
// import { MyComponent } from '@component-package';

// ✅ Use the component's export to import it directly.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'MyComponent',
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;

export default meta;
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

// ❌ Don't use the package's index file to import the component.
// import { MyComponent } from '@component-package';

// ✅ Use the component's export to import it directly.

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'MyComponent',
  component: MyComponent,
});
```

Additionally, if you're developing using TypeScript, you may need to update Storybook's configuration file (i.e., `.storybook/main.js|ts`) to include the following:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    // Overrides the default Typescript configuration to allow multi-package components to be documented via Autodocs.
    reactDocgen: 'react-docgen',
    check: false,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    // Overrides the default Typescript configuration to allow multi-package components to be documented via Autodocs.
    reactDocgen: 'react-docgen',
    check: false,
  },
});
```

If you're still encountering issues, we recommend reaching out to the community using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)).

### The controls are not updating the story within the auto-generated documentation

If you turned off inline rendering for your stories via the [`inline`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md#inline) configuration option, you would run into a situation where the associated controls are not updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release.

**Learn more about Storybook documentation**

- Autodocs for creating documentation for your stories
- [MDX](https://storybook.js.org/docs/writing-docs/mdx.md) for customizing your documentation
- [Doc Blocks](https://storybook.js.org/docs/writing-docs/doc-blocks.md) for authoring your documentation
- [Publishing docs](https://storybook.js.org/docs/writing-docs/build-documentation.md) to automate the process of publishing your documentation
> Source: https://storybook.js.org/docs/writing-docs/autodocs
---

# MDX

[MDX](https://mdxjs.com/) files mix Markdown and Javascript/JSX to create rich interactive documentation. You can use Markdown’s readable syntax (such as `# heading`) for your documentation, include stories defined in [Component Story Format (CSF)](https://storybook.js.org/docs/api/csf.md), and freely embed JSX component blocks at any point in the file. All at once.

In addition, you can write pure documentation pages in MDX and add them to Storybook alongside your stories.

![MDX simple example result](../_assets/writing-docs/mdx-hero.png)

## Basic example

Let's start with an example, `Checkbox.mdx`, combining Markdown with a single story.

```mdx
// Checkbox.mdx

# Checkbox

A checkbox is a square box that can be activated or deactivated when ticked.

Use checkboxes to select one or more options from a list of choices.

```

This MDX file references a story file, `Checkbox.stories.js|ts`, that is written in [Component Story Format (CSF)](https://storybook.js.org/docs/api/csf.md):

```ts
// Checkbox.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Unchecked: Story = {
  args: {
    label: 'Unchecked',
  },
};
```

```ts
// Checkbox.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Checkbox,
});

export const Unchecked = meta.story({
  args: {
    label: 'Unchecked',
  },
});
```

And here's how that's rendered in Storybook:

![MDX simple example result](../_assets/writing-docs/mdx-simple.png)

There’s a lot going on here. We're writing Markdown, we're writing JSX, and we're also defining and referencing Storybook stories that are drop-in compatible with the entire Storybook ecosystem.

Let’s break it down.

### MDX and CSF

The first thing you'll notice is that the component documentation is divided into distinct formats: one for writing component stories describing each possible component state and the second one for documenting how to use them. This split leverages the best qualities of each format:

- **CSF** is great for succinctly defining stories (component examples). If you use TypeScript, it also provides type safety and auto-completion.
- **MDX** is great for writing structured documentation and composing it with interactive JSX elements.

### Anatomy of MDX

Assuming you’re already familiar with writing stories with [CSF](https://storybook.js.org/docs/writing-stories.md), we can dissect the MDX side of things in greater detail.

The document consists of a number of blocks separated by blank lines. Since MDX mixes a few different languages together, it uses those blank lines to help distinguish where one starts, and the next begins. Failing to separate blocks by whitespace can cause (sometimes cryptic) parse errors.

Going through the code blocks in sequence:

```mdx

```

Comments in MDX are JSX blocks that contain JS comments.

```mdx
// Checkbox.mdx

```

Imports the components and stories that will be used in the JSX throughout the rest of the file.

```mdx
// Checkbox.mdx

```

When providing the `of` prop to the `Meta` block, make sure that you're referencing the **full set of exports** of the story file and not the component itself to prevent render issues with the generated documentation.

The `Meta` block defines where the document will be placed in the sidebar. In this case, it is adjacent to the Checkbox’s stories. By default, the docs sidebar node is titled `"Docs"`, but this can be customized by passing a `name` prop (e.g., ``). If you want to place a docs node at an arbitrary point in the navigation hierarchy, you can use the `title` prop (e.g., ``).

```md
# Checkbox

A checkbox is a square box that can be activated or deactivated when ticked.

Use checkboxes to select one or more options from a list of choices.
```

MDX supports standard markdown (["commonmark"](https://commonmark.org/)) by default and can be extended to support [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) and other extensions (see the [Troubleshooting section](#troubleshooting) to learn more about some of the current limitations).

```mdx
// Checkbox.mdx

```

Finally, MDX supports blocks of arbitrary JSX.

In this case, we are leveraging “Doc Blocks”, a library of documentation components designed to work with Storybook stories to show your stories, your component APIs & controls for interacting with your components inside your documentation, among other utilities.

In addition to Doc Blocks, MDX can incorporate arbitrary React components, making it a very flexible documentation system. Suppose you want a stylized list of “dos and don’ts” for your component; you can use off-the-shelf components or write your own.

```mdx
// Guideline.mdx

  
    - Use buttons for the main actions on your page
    - Identify the primary action and make it `primary`
  
  
    - Use a button when a link will do (e.g., for navigation-only actions)
    - Use multiple `primary` buttons in a single UI state
  

```

### Known limitations

While MDX supports a variety of runtimes ([React](https://mdxjs.com/packages/react/), [Preact](https://mdxjs.com/packages/preact/), [Vue](https://mdxjs.com/packages/vue/)), Storybook’s implementation is React-only. That means your documentation is rendered in React, while your stories render in the runtime of your choice (React, Vue, Angular, Web Components, Svelte, etc.).

## Setup custom documentation

In addition, to document your components with MDX, you can also extend it to write other types of content, such as guidelines or best practices on how to use them. To enable custom documentation for your stories with this format, start by updating your Storybook configuration file (i.e., `.storybook/main.js|ts|cjs`).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
  framework: '@storybook/your-framework',
  stories: [
    //👇 Your documentation written in MDX along with your stories goes here
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: ['@storybook/addon-docs'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
  framework: '@storybook/your-framework',
  stories: [
    //👇 Your documentation written in MDX along with your stories goes here
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: ['@storybook/addon-docs'],
});
```

Create an MDX file to add your custom documentation. Depending on how you want your documentation to render in the UI, you'll need to consider the following use cases.

### Using the `Meta` Doc Block

If you need to match the component documentation to an existing story, you can configure the [`Meta`](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md) Doc Block to control how the documentation gets rendered. Out of the box, it allows you to define a custom title or a reference to the story you need to document (i.e., via the `of` prop). For example:

```mdx
// Button.mdx — custom-title

# Definition

Button is a clickable interactive element that triggers a response.

You can place text and icons inside of a button.

Buttons are often used for form submissions and to toggle elements into view.

## Usage

The component comes in different variants such as `primary`, `secondary`, `large` and `small` which you can use to alter the look and feel of the button.

## Inputs

Button has the following properties:

```

```mdx
// Button.mdx — of-prop

# Definition

Button is a clickable interactive element that triggers a response.

You can place text and icons inside of a button.

Buttons are often used for form submissions and to toggle elements into view.

## Usage

The component comes in different variants such as `primary`, `secondary`, `large` and `small` which you can use to alter the look and feel of the button.

## Inputs

Button has the following properties:

```

### Writing unattached documentation

Suppose you're documenting an existing component and only provide the `Meta` Doc Block without additional props or other blocks. In that case, Storybook will consider it as "unattached" documentation, or in other words, a "documentation-only" page, and it will render it differently in the sidebar navigation menu:

```mdx
// ExampleDocumentation.mdx

```

![MDX docs only story](../_assets/writing-docs/mdx-documentation-only.png)

### Using the File System

However, providing the `Meta` Doc Block may not be required for certain use cases, such as standalone pages or even as guidelines for testing your components. In that case, you can safely omit it. Storybook will instead rely on the file's physical location to place the documentation in the sidebar, overriding any pre-existent [auto-generated](https://storybook.js.org/docs/writing-docs/autodocs.md) documentation with your own. For example:

```mdx
// src/components/Select.mdx
# Select

Select is a type of input that allows users to choose one or more options from a list of choices.

The options are hidden by default and revealed when a user interacts with an element.

It shows the currently selected option in its default collapsed state.

## Design implementation

To help users get acquainted with the existing UI elements, it is recommended to use check the Figma file to see how the select input is implemented.

### When to use?

In a select input where there are less than 3-4 items, consider using radio boxes, or radio inputs instead.

### How to use?

To help users understand the options available in a select input, include a default option that is unselectable and acts as a label.
```

If you're overriding an existing auto-generated documentation page enabled via [`tags`](https://storybook.js.org/docs/writing-docs/autodocs.md#set-up-automated-documentation) configuration property, we recommend removing it to avoid errors.

Once the custom MDX documentation is loaded, Storybook will infer the title and location using the same heuristic rules to generate [auto-title stories](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#csf-30-auto-titles) and render it in the sidebar as a `Docs` entry.

#### Working with standalone documentation pages

Writing standalone documentation pages is a common use case that applies not only on a per-component but also on a per-project basis. For example, you might want to document your project's onboarding process with instructions on using it. To do so, you can create a new MDX file containing your documentation using a similar structure and content:

```mdx
// src/GettingStarted.mdx
# Getting Started

Welcome! Whether you're a designer or a developer, this guide will help you get started and connect you to the essential resources you need.

## Table of Contents

- [Design Resources](#design-resources)

  - [Figma](#figma)
  - [UI/UX Design Guidelines](#uiux-design-guidelines)
  - [Design Assets](#design-assets)

- [Development Resources](#development-resources)
  - [Coding Standards](#coding-standards)
  - [Version Control](#version-control)
  - [Development Tools](#development-tools)

---

## Design Resources

### Figma

[Figma](https://www.figma.com/) is a collaborative design and prototyping tool. It's the heart of the design process, allowing designers to work together seamlessly.

- **Get Access**: If you're not already part of the Figma project, request access from the project lead or manager.

### UI/UX Design Guidelines

Before you dive into designing, familiarize yourself with our UI/UX design guidelines. They provide valuable insights into our design philosophy and standards.

- [UI/UX Guidelines Document](https://your-design-guidelines-link.com)

### Design Assets

All the essential design assets like logos, icons, and brand guidelines can be found in the Figma project. Ensure you have access and familiarize yourself with these assets for consistency.

---

## Development Resources

### Coding Standards

Maintaining a consistent code style is essential for collaborative development. Our coding standards document will guide you on best practices.

- [Coding Standards Document](https://your-coding-standards-link.com)

### Version Control

We use Git for version control. Make sure you have Git installed and are familiar with its basics.

### Development Tools

Your development environment is critical. Here are some tools and resources to help you set up your workspace:

- **Code Editor**: We recommend using [Visual Studio Code](https://code.visualstudio.com/) for development. It's highly customizable and supports a wide range of extensions.

- **Package Manager**: [npm](https://www.npmjs.com/) is the package manager we use for JavaScript projects. Install it to manage project dependencies.

---
```

![MDX guidelines page](../_assets/writing-docs/mdx-standalone-page.png)

When Storybook loads the documentation, it will infer the placement of the page in the sidebar navigation menu using the file's physical location and render it as a `Docs` entry.

### Fully control custom documentation

Documentation can be expensive to maintain and keep up to date when applied to every project component. To help simplify this process, Storybook provides a set of useful UI components (i.e., Doc Blocks) to help cover more advanced cases. If you need additional content, use them to help create your custom documentation.

```mdx
// Button.mdx

# Button

Button is a clickable interactive element that triggers a response.

You can place text and icons inside of a button.

Buttons are often used for form submissions and to toggle elements into view.

## Usage

```

### Working with multiple components

If you need to document multiple components in a single documentation page, you can reference them directly inside your MDX file. Internally, Storybook looks for the story metadata and composes it alongside your existing documentation. For example:

```mdx
// Page.mdx

# Page

Page is a layout container that is used to position children in predetermined areas.

It's often used to apply consistent positioning for content across pages in an application

## Usage

# List

List is a grouping of related items. List can be ordered with multiple levels of nesting.

## Usage

# List Item

List items are used to group related content in a list. They must be nested within a List component.

## Usage

```

### Generate documentation from Markdown

If you need to extend your documentation with additional content written in Markdown, you can use the `Markdown` Doc Block to import the available content, and Storybook will render it alongside your existing documentation. For example, if you have a `CHANGELOG.md` file, you can import it and render it in your documentation page as follows:

```mdx
// Changelog.mdx

# Changelog

{Readme}
```

The `Markdown` Doc Block provides additional configuration options to customize the rendering of your documentation. For more information, refer to the [API documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-markdown.md).

![Changelog markdown in an MDX story](../_assets/writing-docs/mdx-markdown-docs-import.png)

### Linking to other stories and pages

Another way to improve documentation is by linking to other stories and pages. Suppose you already have a component story with the following unique identifier, `some--id`, and you want to link it to your documentation page. In that case, you can use the `path` query string to redirect to the documentation entry related to the story:

```md
[Go to specific documentation page](https://storybook.js.org/docs/writing-docs/?path=/docs/some--id.md)
```

Instead, if you need to target a specific documentation section, you can adjust the link to point at it. For example:

```md
[Go to the conclusion of the documentation page](https://storybook.js.org/docs/writing-docs/?path=/docs/some--id.md#conclusion)
```

However, cross-linking documentation isn't restricted to documentation pages. You can adjust the `path` query and supply the story's unique identifier if you need to reference a specific one. For example:

```md
[Go to specific story canvas](https://storybook.js.org/docs/writing-docs/?path=/story/some--id.md)
```

Applying this pattern with the [Controls](https://storybook.js.org/docs/essentials/controls.md) feature, all anchors will be ignored in Canvas based on how Storybook handles URLs to track the args values.

## Troubleshooting

### Markdown tables aren't rendering correctly

If you're extending your documentation to include specific features (e.g., tables, footnotes), you may run into some issues rendering them correctly using the current MDX version supported by Storybook. We recommend enabling the [`remark-gfm`](https://github.com/remarkjs/remark-gfm) plugin in your configuration file (i.e., [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure.md)) to render them correctly.

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other addons go here
    {
      name: '@storybook/addon-docs',
      options: {
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [remarkGfm],
          },
        },
      },
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other addons go here
    {
      name: '@storybook/addon-docs',
      options: {
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [remarkGfm],
          },
        },
      },
    },
  ],
});
```

The [`remark-gfm`](https://github.com/remarkjs/remark-gfm) package is not included by default with Storybook and must be installed separately as a development dependency. To learn more about how to use it and the other breaking changes introduced by MDX, refer to the [GFM guide](https://mdxjs.com/guides/gfm/) and the [migration guide](https://mdxjs.com/migrating/v2/) provided by the MDX team for more information.

### The MDX documentation doesn't render in my environment

As Storybook relies on [MDX 3](https://mdxjs.com/) to render documentation, some technical limitations may prevent you from migrating to this version. If that's the case, we've prepared a set of instructions to help you transition to this new version.

#### Storybook doesn't create documentation for my component stories

If you run into a situation where Storybook is not able to detect and render the documentation for your component stories, it may be due to a misconfiguration in your Storybook. Check your configuration file (i.e., `.storybook/main.js|ts`) and ensure the `stories` configuration element provides the correct path to your stories location (e.g., `../src/**/*.stories.@(js|jsx|mjs|ts|tsx)`).

### The migration seems flaky and keeps failing

By default, running the [migration](https://storybook.js.org/docs/releases/upgrading.md) command will prompt you to update the existing MDX files in your project according to the MDX version supported by Storybook. However, this might be a disruptive process, specifically if you're upgrading from a previous version of Storybook where you were using the legacy MDX format. To help you troubleshoot those issues, we've prepared some recommendations that might help you.

Start by running the following command inside your project directory:

```shell
npx @hipster/mdx2-issue-checker
```

Depending on the volume, you may be required to run the command multiple times to fix all the issues.

When it finishes, it will output the list of files causing issues. You can then use this information to fix the problems manually.

Additionally, if you're working with VSCode, you can add the [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and enable MDX experimental support for linting, type checking, and auto-completion by adding the following to your user settings:

```json
{
  "mdx.server.enable": true
}
```

If you're still encountering issues, we recommend reaching out to the community using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)).

### The controls are not updating the story within the MDX documentation page

If you turned off inline rendering for your stories via the [`inline`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md#inline) configuration option, you would run into a situation where the associated controls are not updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release.

### The React version used is unexpected

For most projects, Storybook's addon-docs uses the React version listed in your project's dependencies. If it does not find one, it will use React 18.2.0. There are two exceptions to this:

- Preact projects will always use React 17
- Next.js projects will always use the canary version that comes with the Next.js version installed, regardless of which React version is listed in the project’s dependencies.

If you're having issues with the React version used, you may need to re-create your project's `node_modules` folder to ensure the correct version is used.

**Learn more about Storybook documentation**

- [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md) for creating documentation for your stories
- MDX for customizing your documentation
- [Doc Blocks](https://storybook.js.org/docs/writing-docs/doc-blocks.md) for authoring your documentation
- [Publishing docs](https://storybook.js.org/docs/writing-docs/build-documentation.md) to automate the process of publishing your documentation
> Source: https://storybook.js.org/docs/writing-docs/mdx
---

# Doc blocks

Storybook offers several doc blocks to help document your components and other aspects of your project.

There are two common ways to use doc blocks in Storybook, within MDX and as part of the docs page template.

## Within MDX

The blocks are most commonly used within Storybook's [MDX documentation](https://storybook.js.org/docs/writing-docs/mdx.md):

![Screenshot of mdx content](../_assets/writing-docs/mdx-example.png)

```mdx title="ButtonDocs.mdx"

# Button

A button is ...

## Props

## Stories

### Primary

A button can be of primary importance.

A button can be of secondary importance.

```

## Customizing the automatic docs page

The blocks are also used to define the page template for [automatics docs](https://storybook.js.org/docs/writing-docs/autodocs.md). For example, here's the default template:

![Screenshot of automatic docs template](../_assets/writing-docs/autodocs-default-template.png)

```jsx

  Title,
  Subtitle,
  Description,
  Primary,
  Controls,
  Stories,
} from '@storybook/addon-docs/blocks';

export const autoDocsTemplate = () => (
  <>
    
    
    
    
    
    
  </>
);
```

If you [override the default page template](https://storybook.js.org/docs/writing-docs/autodocs.md#write-a-custom-template), you can similarly use Doc Blocks to build the perfect documentation page for your project.

Note that some doc blocks render other blocks. For example, the `` block expands to:

```mdx title="Button.mdx"
## Stories

  ### Story name
  
  
  

```

As a result, for example, customizing the [`Source`](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md) block via parameters (see next section) will also affect the Source blocks rendered as part of [`Canvas`](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) blocks.

## Customizing doc blocks

In both use cases (MDX and automatic docs), many of the doc blocks can be customized via [parameters](https://storybook.js.org/docs/writing-stories/parameters.md).

For example, you can filter out the `style` prop from all [`Controls`](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md) tables through your Storybook:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      controls: { exclude: ['style'] },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      controls: { exclude: ['style'] },
    },
  },
});
```

Parameters can also be defined at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) (or meta) level or the [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level, allowing you to customize Doc Blocks exactly as you need, where you need.

The blocks that accept customization via parameters are marked in the list of available blocks below.

When using a doc block in MDX, it can also be customized with its props:

```md
<Controls exclude={['style']}>
```

## Available blocks

Each block has a dedicated API reference page detailing usage, available options, and technical details.

### [ArgTypes](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md)

Accepts parameters in the namespace `parameters.docs.argTypes`.

The `ArgTypes` block can be used to show a static table of [arg types](https://storybook.js.org/docs/api/arg-types.md) for a given component as a way to document its interface.

![Screenshot of ArgTypes block](../_assets/api/doc-block-argtypes.png)

### [Canvas](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md)

Accepts parameters in the namespace `parameters.docs.canvas`.

The `Canvas` block is a wrapper around a [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md), featuring a toolbar that allows you to interact with its content while automatically providing the required [`Source`](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md) snippets.

![Screenshot of Canvas block](../_assets/api/doc-block-canvas.png)

### [ColorPalette](https://storybook.js.org/docs/api/doc-blocks/doc-block-colorpalette.md)

The `ColorPalette` block allows you to document all color-related items (e.g., swatches) used throughout your project.

![Screenshot of ColorPalette and ColorItem blocks](../_assets/api/doc-block-colorpalette.png)

### [Controls](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md)

Accepts parameters in the namespace `parameters.docs.controls`.

The `Controls` block can be used to show a dynamic table of args for a given story, as a way to document its interface, and to allow you to change the args for a (separately) rendered story (via the [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md) or [`Canvas`](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) blocks).

![Screenshot of Controls block](../_assets/api/doc-block-controls.png)

### [Description](https://storybook.js.org/docs/api/doc-blocks/doc-block-description.md)

The `Description` block displays the description for a component, story, or meta obtained from their respective JSDoc comments.

![Screenshot of Description block](../_assets/api/doc-block-title-subtitle-description.png)

### [IconGallery](https://storybook.js.org/docs/api/doc-blocks/doc-block-icongallery.md)

The `IconGallery` block lets you quickly document all icons associated with your project, displayed in a neat grid.

![Screenshot of IconGallery and IconItem blocks](../_assets/api/doc-block-icongallery.png)

### [Markdown](https://storybook.js.org/docs/api/doc-blocks/doc-block-markdown.md)

The `Markdown` block allows you to import and include plain markdown in your MDX files.

![Screenshot of Markdown block](../_assets/api/doc-block-markdown.png)

### [Meta](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md)

The `Meta` block is used to [attach](#attached-vs-unattached) a custom MDX docs page alongside a component’s list of stories. It doesn’t render any content but serves two purposes in an MDX file:

- Attaches the MDX file to a component and its stories, or
- Controls the location of the unattached docs entry in the sidebar.

### [Primary](https://storybook.js.org/docs/api/doc-blocks/doc-block-primary.md)

The `Primary` block displays the primary (first defined in the stories file) story in a [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md) block. It is typically rendered immediately under the title in a docs entry.

![Screenshot of Primary block](../_assets/api/doc-block-primary.png)

### [Source](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md)

Accepts parameters in the namespace `parameters.docs.source`.

The `Source` block is used to render a snippet of source code directly.

![Screenshot of Source block](../_assets/api/doc-block-source.png)

### [Stories](https://storybook.js.org/docs/api/doc-blocks/doc-block-stories.md)

The `Stories` block renders the full collection of stories in a stories file.

![Screenshot of Stories block](../_assets/api/doc-block-stories.png)

### [Story](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md)

Accepts parameters in the namespace `parameters.docs.story`.

[Stories](https://storybook.js.org/docs/writing-stories.md) are Storybook's fundamental building blocks.

In Storybook Docs, you can render any of your stories from your CSF files in the context of an MDX file with all annotations (parameters, args, loaders, decorators, play function) applied using the `Story` block.

![Screenshot of Story block](../_assets/api/doc-block-story.png)

### [Subtitle](https://storybook.js.org/docs/api/doc-blocks/doc-block-subtitle.md)

The `Subtitle` block can serve as a secondary heading for your docs entry.

![Screenshot of Subtitle block](../_assets/api/doc-block-title-subtitle-description.png)

### [TableOfContents](https://storybook.js.org/docs/api/doc-blocks/doc-block-tableofcontents.md)

Accepts parameters in the namespace `parameters.docs.toc`.

The `TableOfContents` block renders a table of contents for the current documentation page, allowing users to quickly navigate between sections. It appears as a fixed sidebar on the right side of the page.

### [Title](https://storybook.js.org/docs/api/doc-blocks/doc-block-title.md)

The `Title` block serves as the primary heading for your docs entry. It is typically used to provide the component or page name.

![Screenshot of Title block](../_assets/api/doc-block-title-subtitle-description.png)

### [Typeset](https://storybook.js.org/docs/api/doc-blocks/doc-block-typeset.md)

The `Typeset` block helps document the fonts used throughout your project.

![Screenshot of Typeset block](../_assets/api/doc-block-typeset.png)

### [Unstyled](https://storybook.js.org/docs/api/doc-blocks/doc-block-unstyled.md)

The `Unstyled` block is a unique block that disables Storybook's default styling in MDX docs wherever it is added.

By default, most elements (like `h1`, `p`, etc.) in docs have a few default styles applied to ensure the docs look good. However, sometimes you might want some of your content not to have these styles applied. In those cases, wrap the content with the `Unstyled` block to remove the default styles.

![Screenshot of Unstyled block](../_assets/api/doc-block-unstyled.png)

## Make your own Doc Blocks

Storybook also provides a [`useOf` hook](https://storybook.js.org/docs/api/doc-blocks/doc-block-useof.md) to make it easier to create your own blocks that function like the built-in blocks.

## Troubleshooting

### Why can't I use the Doc Blocks inside my stories?

Storybook's Doc Blocks are highly customizable and helpful building blocks to assist you with building your custom documentation. Although most of them enable you to customize them with parameters or globally to create custom [documentation templates](#customizing-the-automatic-docs-page), they are primarily designed for MDX files. For example, if you try to add the `ColorPalette` block to your stories as follows, you'll get an error message when the story loads in Storybook.

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

const theme = {
  colors: {
    primaryDark: {
      value: '#1C1C1C',
    },
    primaryRegular: {
      value: '#363636',
    },
    primaryLight1: {
      value: '#4D4D4D',
    },
    primaryLight2: {
      value: '#878787',
    },
    primaryLight3: {
      value: '#D1D1D1',
    },
    primaryLight4: {
      value: '#EDEDED',
    },
  },
};

// ❌ Don't use the Doc Blocks inside your stories. It will break Storybook with a cryptic error.
export const Colors: Story = {
  render: () => (
    
      {Object.entries(theme.colors).map(([key, { value }]) => (
        
      ))}
    
  ),
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

const theme = {
  colors: {
    primaryDark: {
      value: '#1C1C1C',
    },
    primaryRegular: {
      value: '#363636',
    },
    primaryLight1: {
      value: '#4D4D4D',
    },
    primaryLight2: {
      value: '#878787',
    },
    primaryLight3: {
      value: '#D1D1D1',
    },
    primaryLight4: {
      value: '#EDEDED',
    },
  },
};

// ❌ Don't use the Doc Blocks inside your stories. It will break Storybook with a cryptic error.
export const Colors = meta.story({
  render: () => (
    
      {Object.entries(theme.colors).map(([key, { value }]) => (
        
      ))}
    
  ),
});
```

**Learn more about Storybook documentation**

- [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md) for creating documentation for your stories
- [MDX](https://storybook.js.org/docs/writing-docs/mdx.md) for customizing your documentation
- Doc Blocks for authoring your documentation
- [Publishing docs](https://storybook.js.org/docs/writing-docs/build-documentation.md) to automate the process of publishing your documentation
> Source: https://storybook.js.org/docs/writing-docs/doc-blocks
---

# Code panel

Code Panel is a replacement for the [Storysource addon](https://storybook.js.org/addons/@storybook/addon-storysource), which was [discontinued in Storybook 9](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#storysource-addon-removed).

The Code panel renders a story’s source code when viewing that story in the canvas. Any [args](https://storybook.js.org/docs/writing-stories/args.md) defined in the story are replaced with their values in the output.

![Code panel showing story's source code](../_assets/writing-docs/code-panel.png)

## Usage

To enable the Code panel, set `parameters.docs.codePanel` to `true`. For most projects, this is best done in the `.storybook/preview.*` file, to apply to all stories.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)

const preview: Preview = {
  parameters: {
    docs: {
      codePanel: true,
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    docs: {
      codePanel: true,
    },
  },
});
```

You can also enable it at the component or story level:

```ts
// Button.stories.ts|tsx — CSF 3

const meta = {
  component: Button,
  parameters: {
    docs: {
      // 👇 Enable Code panel for all stories in this file
      codePanel: true,
    },
  },
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

// 👇 This story will display the Code panel
export const Primary: Story = {
  args: {
    children: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    children: 'Button',
    variant: 'secondary',
  },
  parameters: {
    docs: {
      // 👇 Disable Code panel for this specific story
      codePanel: false,
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    docs: {
      // 👇 Enable Code panel for all stories in this file
      codePanel: true,
    },
  },
});

// 👇 This story will display the Code panel
export const Primary = meta.story({
  args: {
    children: 'Button',
  },
});

export const Secondary = meta.story({
  args: {
    children: 'Button',
    variant: 'secondary',
  },
  parameters: {
    docs: {
      // 👇 Disable Code panel for this specific story
      codePanel: false,
    },
  },
});
```

## Configuration

Code panel renders the same snippet as the [Source docs block](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md), which is also used in [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md) pages. The snippet is customizable and reuses the [Source configuration parameters](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md#source).
> Source: https://storybook.js.org/docs/writing-docs/code-panel
---

# Preview and build docs

Storybook allows you to create rich and extensive [documentation](https://storybook.js.org/docs/writing-docs.md) that will help you and any other stakeholder involved in the development process. Out of the box you have the tooling required to not only write it but also to preview it and build it.

## Preview Storybook's documentation

At any point during your development, you can preview the documentation you've written. Storybook allows you to generate a preview of the final documentation when you use the `--docs` flag. We recommend including it in your `package.json` as a new script:

```json title="package.json"
{
  "scripts": {
    "storybook-docs": "storybook dev --docs"
  }
}
```

Depending on your configuration, when you execute the `storybook-docs` script. Storybook will be put into documentation mode and will generate a different build.

It will look for any stories available either in [MDX](https://storybook.js.org/docs/writing-docs/mdx.md) or [CSF](https://storybook.js.org/docs/writing-stories/index.md#component-story-format) and based on the documentation you've added it will display it...

![Storybook in documentation mode](../_assets/writing-docs/storybook-docs-build.png)

There's some caveats to this build mode, as to the normal Storybook build:

- The top level item refers to the primary story for your component.
- Each individual story is now in a flattened display mode, with a different set of icons. This allows focus on the documentation itself.
- Storybook's layout is rendered differently. The toolbar will not be displayed.

## Publish Storybook's documentation

You can also publish your documentation the same you would [publish](https://storybook.js.org/docs/sharing/publish-storybook.md) your Storybook. You can use the `--docs` flag with the [`storybook build`](https://storybook.js.org/docs/api/cli-options.md#build) command. We recommend as well including it as a script in your `package.json` file:

```json title="package.json"
{
  "scripts": {
    "build-storybook-docs": "storybook build --docs"
  }
}
```

Based on the configuration you have, when the `build-storybook-docs` script is executed, Storybook once again will be put into documentation mode and will generate a different build and output the documentation into the `storybook-static` folder.

The same caveats mentioned above will apply.

You can use any hosting provider to deploy your documentation, for instance:

- [Vercel](https://vercel.com/)
- [Netlify](https://www.netlify.com/)
- [S3](https://aws.amazon.com/en/s3/)

**Learn more about Storybook documentation**

- [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md) for creating documentation for your stories
- [MDX](https://storybook.js.org/docs/writing-docs/mdx.md) for customizing your documentation
- [Doc Blocks](https://storybook.js.org/docs/writing-docs/doc-blocks.md) for authoring your documentation
- Publishing docs to automate the process of publishing your documentation
> Source: https://storybook.js.org/docs/writing-docs/build-documentation
---

# Using Storybook with AI

Storybook's AI capabilities are currently in [preview](https://storybook.js.org/docs/releases/features.md#preview) and only supported for [React](https://storybook.js.org/docs/ai/?renderer=react.md) projects.

The API may change in future releases. We welcome feedback and contributions to help improve this feature.

Storybook's AI capabilities help you get more out of agentic development at every stage, from adding Storybook to a project to working with your components day to day.

[Agentic setup](https://storybook.js.org/docs/ai/setup.md) configures Storybook for you and writes an initial set of stories for your project. The [Storybook MCP server](https://storybook.js.org/docs/ai/mcp/overview.md) gives your agent ongoing access to your component documentation, story generation, and component tests.

## Set up Storybook with an agent

[Agentic setup](https://storybook.js.org/docs/ai/setup.md) analyzes your project and produces step-by-step instructions that an agent follows to add Storybook, configure the preview, write stories for your components, and verify them.

To get started, run this prompt in your agent:

```shell
Set up Storybook for me with npm create storybook@latest and follow its instructions precisely
```

For the full walkthrough, see the [agentic setup guide](https://storybook.js.org/docs/ai/setup.md).

## Connect your agent to Storybook

Once Storybook is set up, connect your agent to the Storybook MCP server so it can read [manifests](https://storybook.js.org/docs/ai/manifests.md) of your components and documentation, generate stories, and run tests against your live Storybook.

### 1. Install the addon

Run this command to install and register the Storybook MCP addon:

```shell
npx storybook add @storybook/addon-mcp
```

```shell
pnpm exec storybook add @storybook/addon-mcp
```

```shell
yarn exec storybook add @storybook/addon-mcp
```

Now, when running Storybook's dev server, you can access the MCP server at `http://localhost:6006/mcp` (your port may be different). When viewed in the browser, you'll see a page showing which tools are available and a link to the [manifest debugger](https://storybook.js.org/docs/ai/manifests.md#debugging).

![The MCP server page in the browser](../_assets/ai/addon-mcp-splash.png)

### 2. Add the MCP server to your agent

Then run this command to configure your agent to use the MCP server:

```shell
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

```shell
pnpm exec mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

```shell
yarn exec mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

You may need to update the port number in the URL. You will be prompted for a name for your MCP server (e.g. "my-project-sb-mcp"). This is the name you'll use when calling the tools from your agent, so choose something descriptive and unique to avoid confusion with other tools.

[`mcp-add`](https://github.com/paoloricciuti/mcp-add) is a CLI tool designed to simplify adding MCP servers to various agents.

You can also follow your agent's documentation to add the MCP server as a tool provider manually, e.g. [Claude Code](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server), [Google Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#adding-an-http-server), [OpenAI Codex](https://developers.openai.com/codex/mcp/), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_configure-the-mcpjson-file), etc.

### 3. Adjust your agent instructions

To guide your agent to use your MCP server, you should adjust your [`AGENTS.md`](https://agents.md/) (or [`CLAUDE.md`](https://code.claude.com/docs/en/memory#claude-md-files), if you're using Claude). The specifics will depend on your project and how you use agents in your development process, but something like this is a good starting point. Just make sure to replace `your-project-sb-mcp` with the name you chose for your MCP server toolset in the previous step.

<details>
<summary>Example instructions for AGENTS.md</summary>

```md title="AGENTS.md"
When working on UI components, always use the `your-project-sb-mcp` MCP tools to access Storybook's component and documentation knowledge before answering or taking any action.

- **CRITICAL: Never hallucinate component properties!** Before using ANY property on a component from a design system (including common-sounding ones like `shadow`, etc.), you MUST use the MCP tools to check if the property is actually documented for that component.
- Query `list-all-documentation` to get a list of all components
- Query `get-documentation` for that component to see all available properties and examples
- Only use properties that are explicitly documented or shown in example stories
- If a property isn't documented, do not assume properties based on naming conventions or common patterns from other libraries. Check back with the user in these cases.
- Use the `get-storybook-story-instructions` tool to fetch the latest instructions for creating or updating stories. This will ensure you follow current conventions and recommendations.
- Check your work by running `run-story-tests`.

Remember: A story name might not reflect the property name correctly, so always verify properties through documentation or example stories before using them.
```

</details>

Finally, test your agent's access to the MCP server. First, make sure your Storybook is running, then run a prompt like "List all documented components". You should see a call to the [`list-all-documentation`](https://storybook.js.org/docs/ai/mcp/overview.md#list-all-documentation) tool with a response listing components from your Storybook.

## Key concepts

Understanding these concepts will help you make the most of Storybook's AI capabilities and guide you in choosing the right tool for each stage of your workflow.

### Agentic setup

When you add Storybook to a project using an agent, Storybook generates project-specific instructions tailored to your framework, renderer, builder, language, and addons. An agent can follow those instructions to configure Storybook's preview, support patterns like portals and providers, mock side effects, write stories for your components, add interaction tests, and verify the result.

### Manifests

Storybook collects all of the metadata about your components, stories, and docs into [manifests](https://storybook.js.org/docs/ai/manifests.md). Each manifest is a JSON object that serves as a comprehensive map of your Storybook's content and structure. There are manifests for components, based on stories files, and for documentation, based on MDX files.

These manifests are automatically generated and updated as you work on your Storybook, ensuring that your agent always has access to the latest information about your project.

### MCP server

[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is a standard for communication between AI agents and external tools. Storybook's [MCP server](https://storybook.js.org/docs/ai/mcp.md) exposes your Storybook's content and functionality as a set of tools that your agent can call to retrieve component information, generate stories, run component tests, and more.

**More AI resources**

- [Agentic setup](https://storybook.js.org/docs/ai/setup.md)
- [MCP server overview](https://storybook.js.org/docs/ai/mcp/overview.md)
- [MCP server API](https://storybook.js.org/docs/ai/mcp/api.md)
- [Sharing your MCP server](https://storybook.js.org/docs/ai/mcp/sharing.md)
- [Best practices for using Storybook with AI](https://storybook.js.org/docs/ai/best-practices.md)
- [Manifests](https://storybook.js.org/docs/ai/manifests.md)
> Source: https://storybook.js.org/docs/ai
---

# Agentic setup

Storybook's agentic setup is currently only available for projects using the [React](https://storybook.js.org/docs/ai/?renderer=react.md) renderer with the [Vite](https://storybook.js.org/docs/builders/vite.md) builder. Support for additional renderers and builders will follow.

The API may change in future releases. We welcome feedback and contributions to help improve this feature.

Configuring Storybook in an existing application is repetitive, project-specific work that AI agents handle well. When you add Storybook to a project using an agent, it analyzes your project (framework, renderer, builder, language, addons) and produces a Markdown guide with [step-by-step instructions](#generated-setup-instructions). By following this guide, your agent will configure your preview file, set up commonly needed mocks, and write stories for components in your codebase.

After an agent follows those instructions, you have a working Storybook with stories for your components and a clear path to expanding coverage across your codebase.

## Set up Storybook with an agent

To set up Storybook in your project, copy/paste this prompt into your agent's chat:

```shell
Set up Storybook for me with npm create storybook@latest and follow its instructions precisely
```

The agent first runs [`storybook init`](https://storybook.js.org/docs/api/cli-options.md#init) to add Storybook to your project. When init completes, the agent offers to continue with project-specific configuration. If you agree, the agent generates the instructions, follows them step by step, and applies each change directly to your codebase so you can review its work.

### Generated setup instructions

The project-specific instructions cover the following steps:

1. **Analyze the codebase:** read providers, global CSS, portals, and data-fetching patterns.
2. **Configure the [preview](https://storybook.js.org/docs/configure/story-rendering.md):** set up [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [global styles](https://storybook.js.org/docs/configure/styling-and-css.md), and any framework-level providers in `preview.tsx`.
3. **Support portals:** ensure portal roots exist in the Storybook preview DOM.
4. **Mock side effects:** intercept [network requests](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-network-requests.md) (via MSW), storage, timers, and navigation at the preview level rather than per-story.
5. **Write [stories](https://storybook.js.org/docs/writing-stories.md):** add stories from up to 10 components, from simple to complex, [tagging](https://storybook.js.org/docs/writing-stories/tags.md) them as `ai-generated` for your review.
6. **Add [play functions](https://storybook.js.org/docs/writing-stories/play-function.md):** implement [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md) for the most important flows.
7. **Cover additional patterns:** expand coverage across the components the agent has already touched.
8. **Verify:** run [Vitest](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md) against every new story to confirm it renders, and run the type checker.
9. **Install useful addons:** add and configure addons like [MCP](https://storybook.js.org/docs/ai/mcp/overview.md) to help you (and your agent) get the most out of Storybook.

## Next steps

Once the agent has completed the setup:

- [Run your new Storybook](https://storybook.js.org/docs/get-started/install.md#start-storybook) and review the generated configuration files ([main](https://storybook.js.org/docs/configure/index.md#configure-your-storybook-project) and [preview](https://storybook.js.org/docs/configure/index.md#configure-story-rendering), most importantly).
- Review the stories tagged `ai-generated`, and remove the tag once you've validated each one.
- Connect the [Storybook MCP server](https://storybook.js.org/docs/ai/mcp/overview.md) to your agent so it can continue reading manifests, generating stories, and running tests against your live Storybook.
- Follow the [best practices](https://storybook.js.org/docs/ai/best-practices.md) to make your stories and documentation maximally useful to both humans and agents.

**More AI resources**

- [MCP server overview](https://storybook.js.org/docs/ai/mcp/overview.md)
- [MCP server API](https://storybook.js.org/docs/ai/mcp/api.md)
- [Sharing your MCP server](https://storybook.js.org/docs/ai/mcp/sharing.md)
- [Best practices for using Storybook with AI](https://storybook.js.org/docs/ai/best-practices.md)
- [Manifests](https://storybook.js.org/docs/ai/manifests.md)
> Source: https://storybook.js.org/docs/ai/setup
---

# MCP server

While they are in [preview](https://storybook.js.org/docs/releases/features.md#preview), Storybook's AI capabilities (specifically, the [manifests](https://storybook.js.org/docs/ai/manifests.md) and MCP server) are currently only supported for [React](https://storybook.js.org/docs/ai/mcp/?renderer=react.md) projects.

Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature.

Storybook's MCP server connects your Storybook to AI agents, allowing them to understand your components and documentation, generate stories, run tests, and more. Agents will be equipped to reuse your existing components and follow your documented usage guidelines when generating UI, helping ensure the generated UI is consistent with your existing design system. Then they can write stories so you can preview the generated UI and automatically run interaction tests (and accessibility checks) on those stories to validate their work. If any issues are found, the agent can fix them and re-run the tests to confirm they are resolved, creating a self-healing loop that helps ensure the quality of the generated UI without requiring you to intervene.

## Installation

### 1. Install the addon

Run this command to install and register the Storybook MCP addon:

```shell
npx storybook add @storybook/addon-mcp
```

```shell
pnpm exec storybook add @storybook/addon-mcp
```

```shell
yarn exec storybook add @storybook/addon-mcp
```

Now, when running Storybook's dev server, you can access the MCP server at `http://localhost:6006/mcp` (your port may be different). When viewed in the browser, you'll see a page showing which tools are available and a link to the [manifest debugger](https://storybook.js.org/docs/ai/manifests.md#debugging).

![The MCP server page in the browser](../../_assets/ai/addon-mcp-splash.png)

### 2. Add the MCP server to your agent

Then run this command to configure your agent to use the MCP server:

```shell
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

```shell
pnpm exec mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

```shell
yarn exec mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

You may need to update the port number in the URL. You will be prompted for a name for your MCP server (e.g. "my-project-sb-mcp"). This is the name you'll use when calling the tools from your agent, so choose something descriptive and unique to avoid confusion with other tools.

[`mcp-add`](https://github.com/paoloricciuti/mcp-add) is a CLI tool designed to simplify adding MCP servers to various agents.

You can also follow your agent's documentation to add the MCP server as a tool provider manually, e.g. [Claude Code](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server), [Google Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#adding-an-http-server), [OpenAI Codex](https://developers.openai.com/codex/mcp/), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_configure-the-mcpjson-file), etc.

### 3. Adjust your agent instructions

To guide your agent to use your MCP server, you should adjust your [`AGENTS.md`](https://agents.md/) (or [`CLAUDE.md`](https://code.claude.com/docs/en/memory#claude-md-files), if you're using Claude). The specifics will depend on your project and how you use agents in your development process, but something like this is a good starting point. Just make sure to replace `your-project-sb-mcp` with the name you chose for your MCP server toolset in the previous step.

```md title="AGENTS.md"
When working on UI components, always use the `your-project-sb-mcp` MCP tools to access Storybook's component and documentation knowledge before answering or taking any action.

- **CRITICAL: Never hallucinate component properties!** Before using ANY property on a component from a design system (including common-sounding ones like `shadow`, etc.), you MUST use the MCP tools to check if the property is actually documented for that component.
- Query `list-all-documentation` to get a list of all components
- Query `get-documentation` for that component to see all available properties and examples
- Only use properties that are explicitly documented or shown in example stories
- If a property isn't documented, do not assume properties based on naming conventions or common patterns from other libraries. Check back with the user in these cases.
- Use the `get-storybook-story-instructions` tool to fetch the latest instructions for creating or updating stories. This will ensure you follow current conventions and recommendations.
- Check your work by running `run-story-tests`.

Remember: A story name might not reflect the property name correctly, so always verify properties through documentation or example stories before using them.
```

Finally, test your agent's access to the MCP server. First, make sure your Storybook is running, then run a prompt like "List all documented components". You should see a call to the [`list-all-documentation`](#list-all-documentation) tool with a response listing components from your Storybook.

## Usage

Once you have your MCP server and agent configured, using it is as simple as prompting your agent to do some UI development. Let's demonstrate how these toolsets can work together in some typical workflows.

**1. Generating UI with existing components**

_Prompt: Build a login form_

1. The agent queries the [docs toolset](#docs) to find components that match the requirements of a login form, e.g. a `TextInput` component for the username and password fields, and a `Button` component for the submit button.

1. The agent queries the [docs toolset](#docs) again to reference more detailed information about specific components, e.g., it learns that the `TextInput` component has a `type` prop that can be set to "password" to obscure the input.

1. The agent generates a LoginForm component that composes those components together.

1. The agent uses the [development toolset](#development) to generate stories that render LoginForm in its various states.

1. The agent uses the [testing toolset](#testing) to run tests on the generated component, and finds that the submit button does not have an accessible level of color contrast.

1. The agent updates the LoginForm component to use a different color (found by using the [docs toolset](#docs) to reference your documented theme colors) for the submit button.

1. The agent uses the [testing toolset](#testing) to re-run the tests to confirm that the issue is resolved.
1. The agent uses the [development toolset](#development) to show you previews of each relevant story.

**2. Previewing work with stories**

_Prompt: Show me the Button in dark mode_

1. The agent uses the [development toolset](#development) to share a preview of or link to the default Button story in dark mode.

**3. Running tests**

_Prompt: Run tests for all the stories that contain the Header component_

1. Agent uses grep (or "file system lookup") to determine which components use Header.

1. Agent finds all the stories for those components.

1. The agent uses the [testing toolset](#testing) to run tests on those stories, and returns a summary of the results.

**4. Generating tests**

_Prompt: Write a story to test the login form submit action_

1. The agent uses the [development toolset](#development) to generate a story that demonstrates the submit action of the login form, e.g. by writing a [play function](https://storybook.js.org/docs/writing-tests/interaction-testing.md#writing-interaction-tests) to simulate a user filling out the form and clicking the submit button, then asserting that the expected outcome occurs (e.g. a success message appears, the user is redirected, etc.).

## Toolsets

The MCP server provides a set of tools that an agent can call to interact with your Storybook. The available tools are organized into three toolsets: development, docs, and testing. Each toolset provides a different set of capabilities for the agent to use when developing UI.

### Development

The development toolset provides tools for authoring well-considered stories (including [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md)) and previewing those stories in the agent's chat interface. This allows you to easily check the agent's work, and the generated stories can serve as tests (which the agent can run, with the [testing toolset](#testing), to validate that the generated UI works as intended).

The development toolset includes the following tools:

#### `get-changed-stories`

Returns a list of stories that are changed or possibly affected by local file changes (requires [change detection](https://storybook.js.org/docs/configure/user-interface/change-detection.md) to be enabled).

#### `get-storybook-story-instructions`

Returns instructions on how to write useful stories, including which props to capture and how to write interaction tests for the story (if applicable).

#### `preview-stories`

Returns story previews rendered in the agent's chat interface, if the agent supports [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support). Otherwise, it returns links to relevant stories in Storybook.

### Docs

The docs toolset provides tools that help the agent reuse components from your Storybook when generating UI. The agent can query the manifests to find components that match the requirements of the UI it's trying to build, and reference your documentation to understand how to use those components correctly. This helps ensure the generated UI is consistent with your existing design system and uses the components you've already built.

The docs toolset includes the following tools:

#### `get-documentation`

Returns the detailed documentation for a specific component, including its props, the first three stories, an index of the remaining stories, and any additional documentation you've provided.

#### `get-documentation-for-story`

Returns the full story and associated documentation for a specific story. The agent calls this tool when `get-documentation` doesn't provide enough information for the agent to use a component effectively.

#### `list-all-documentation`

Returns an index containing components and unattached docs entries.

### Testing

If you have [Storybook Test](https://storybook.js.org/docs/writing-tests.md) set up in your Storybook, the testing toolset provides tools that allow the agent to run component tests (including [accessibility checks](https://storybook.js.org/docs/writing-tests/accessibility-testing.md), if set up) and interpret their results. It also includes instructions to resolve issues. As the agent develops, it can choose to run tests to validate its work. If it finds issues, it can fix them and re-run the tests to confirm they are resolved. This creates a _self-healing_ loop that helps ensure the quality of the generated UI, without requiring you to intervene.

The testing toolset includes the following tool:

#### `run-story-tests`

Runs tests for specific stories and returns results, including any accessibility issues (if configured). Also instructs the agent to interpret the results and resolve any issues found.

## Composition

If you need to develop UI using components from multiple Storybooks, you can take advantage of [Storybook composition](https://storybook.js.org/docs/sharing/storybook-composition.md). If a composed Storybook has [manifests](https://storybook.js.org/docs/ai/manifests.md), the MCP server will automatically include the content from those manifests in its responses, allowing your agent to access the combined knowledge from all composed Storybooks. This means that your agent can find and reference components from any of the composed Storybooks when generating UI.

## FAQ

### Which agents are supported?

We built Storybook's capabilities as an MCP server, which is a standard protocol for AI agent tool providers. Any agent that supports MCP can be connected to Storybook's MCP server, and will be able to use Storybook's manifests and tools. This includes popular agents like [Claude](https://claude.ai/), [Google Gemini](https://gemini.google.dev/), [Microsoft Copilot](https://copilot.microsoft.com/), and many more.

### Why is the docs toolset React-only?

The docs toolset relies on the [manifests](https://storybook.js.org/docs/ai/manifests.md) generated by Storybook, which is currently limited to React projects. After we ensure a solid experience with React projects, we plan to expand support to the other core Storybook renderers: Vue, Angular, Web Components, and Svelte.

**More AI resources**

- [Agentic setup](https://storybook.js.org/docs/ai/setup.md)
- [MCP server API](https://storybook.js.org/docs/ai/mcp/api.md)
- [Sharing your MCP server](https://storybook.js.org/docs/ai/mcp/sharing.md)
- [Best practices for using Storybook with AI](https://storybook.js.org/docs/ai/best-practices.md)
- [Manifests](https://storybook.js.org/docs/ai/manifests.md)
> Source: https://storybook.js.org/docs/ai/mcp/overview
---

# MCP server API

While they are in [preview](https://storybook.js.org/docs/releases/features.md#preview), Storybook's AI capabilities (specifically, the [manifests](https://storybook.js.org/docs/ai/manifests.md) and MCP server) are currently only supported for [React](https://storybook.js.org/docs/ai/mcp/?renderer=react.md) projects.

Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature.

## `@storybook/addon-mcp` options

The MCP server addon accepts the following options to configure the tools provided by the MCP server. You can provide these options when registering the addon in your `main.js|ts` file:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // ... your existing addons
    {
      name: '@storybook/addon-mcp',
      options: {
        toolsets: {
          dev: false,
        },
      },
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // ... your existing addons
    {
      name: '@storybook/addon-mcp',
      options: {
        toolsets: {
          dev: false,
        },
      },
    },
  ],
});
```

### `toolsets`

Type:

```ts
{
  dev?: boolean;
  docs?: boolean;
  test?: boolean;
}
```

Default:

```ts
{
  dev: true,
  docs: true,
  test: true,
}
```

Configuration object to toggle which toolsets are enabled in the MCP server. By default, all toolsets are enabled.

#### `dev`

Type: `boolean`

Default: `true`

The development toolset includes the [`get-changed-stories`](https://storybook.js.org/docs/ai/mcp/overview.md#get-changed-stories), [`get-storybook-story-instructions`](https://storybook.js.org/docs/ai/mcp/overview.md#get-storybook-story-instructions), and [`preview-stories`](https://storybook.js.org/docs/ai/mcp/overview.md#preview-stories) tools.

#### `docs`

Type: `boolean`

Default: `true`

The docs toolset includes the [`get-documentation`](https://storybook.js.org/docs/ai/mcp/overview.md#get-documentation), [`get-documentation-for-story`](https://storybook.js.org/docs/ai/mcp/overview.md#get-documentation-for-story), and [`list-all-documentation`](https://storybook.js.org/docs/ai/mcp/overview.md#list-all-documentation) tools.

#### `test`

Type: `boolean`

Default: `true`

The testing toolset includes the [`run-story-tests`](https://storybook.js.org/docs/ai/mcp/overview.md#run-story-tests) tool.

**More AI resources**

- [Agentic setup](https://storybook.js.org/docs/ai/setup.md)
- [MCP server overview](https://storybook.js.org/docs/ai/mcp/overview.md)
- [Sharing your MCP server](https://storybook.js.org/docs/ai/mcp/sharing.md)
- [Best practices for using Storybook with AI](https://storybook.js.org/docs/ai/best-practices.md)
- [Manifests](https://storybook.js.org/docs/ai/manifests.md)
> Source: https://storybook.js.org/docs/ai/mcp/api
---

# Sharing your MCP server

While they are in [preview](https://storybook.js.org/docs/releases/features.md#preview), Storybook's AI capabilities (specifically, the [manifests](https://storybook.js.org/docs/ai/manifests.md) and [MCP server](https://storybook.js.org/docs/ai/mcp/overview.md)) are currently only supported for [React](https://storybook.js.org/docs/ai/mcp/?renderer=react.md) projects.

Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature.

Just as [publishing your Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md) can help your team work more effectively, sharing your MCP server can enable your team to share the benefits of AI-assisted development.

The MCP server is made of [development](https://storybook.js.org/docs/ai/mcp/overview.md#development), [docs](https://storybook.js.org/docs/ai/mcp/overview.md#docs), and [testing](https://storybook.js.org/docs/ai/mcp/overview.md#testing) toolsets that an agent can call to interact with your Storybook. The development and testing toolsets are only relevant to the locally-running Storybook instance, but the docs toolset can be published and shared so that agents outside of your local environment can access the knowledge from your Storybook's [manifest](https://storybook.js.org/docs/ai/manifests.md) to reference your components and documentation when generating UI.

There are two different ways you can share your MCP server.

## Automatic publishing with Chromatic

The easiest way to share your MCP server is to [publish your Storybook with Chromatic](https://storybook.js.org/docs/sharing/publish-storybook.md#publish-storybook-with-chromatic), which will [automatically publish your MCP server](https://chromatic.com/docs/mcp/) as well. If your Storybook is private, your MCP server will be private as well, and only accessible to those you invite to your Chromatic project. If your Storybook is public, your MCP server will be public as well, and accessible to anyone with the URL.

Once published, you can share the [MCP server URL](https://chromatic.com/docs/mcp/#grab-your-mcp-server-url) with your team or community, and they can configure their agent to use that URL to access it.

By publishing with Chromatic, you can be sure that your MCP server is always up-to-date with your latest Storybook, it's safeguarded by UI tests, and you don't have to worry about hosting or maintaining it yourself.

## Self-hosting with `@storybook/mcp`

If you prefer full control over your MCP server, you can self-host it. This approach allows you to manage the server's infrastructure, security, and updates according to your team's requirements. You will need to ensure your MCP server is accessible to your team or community and properly maintained.

We provide a package, `@storybook/mcp`, which is a library that creates a [`tmcp`-based](https://github.com/paoloricciuti/tmcp/) MCP server exposing Storybook component/docs knowledge from [manifests](https://storybook.js.org/docs/ai/manifests.md).

### Prerequisites

- Node.js 20+
- A [manifest](https://storybook.js.org/docs/ai/manifests.md) source containing:
  - `components.json` (required)
  - `docs.json` (optional)

### API

The full API for `@storybook/mcp` is documented in the [package's repository](https://github.com/storybookjs/mcp/tree/main/packages/mcp).

### Example implementation

You can reference [self-hosting patterns](https://github.com/storybookjs/mcp/tree/main/apps/self-host-mcp) for both a Node.js process and a Netlify Function.

This is the minimal implementation of a server using `@storybook/mcp`:

```ts title="server.ts"

const storybookMcpHandler = await createStorybookMcpHandler();

export async function handleRequest(request: Request): Promise<Response> {
  if (new URL(request.url).pathname === '/mcp') {
    return storybookMcpHandler(request);
  }

  return new Response('Not found', { status: 404 });
}
```

**More AI resources**

- [Agentic setup](https://storybook.js.org/docs/ai/setup.md)
- [MCP server overview](https://storybook.js.org/docs/ai/mcp/overview.md)
- [MCP server API](https://storybook.js.org/docs/ai/mcp/api.md)
- [Best practices for using Storybook with AI](https://storybook.js.org/docs/ai/best-practices.md)
- [Manifests](https://storybook.js.org/docs/ai/manifests.md)
> Source: https://storybook.js.org/docs/ai/mcp/sharing
---

# Best practices for using Storybook with AI

The best practices here relate to the [generated manifests](https://storybook.js.org/docs/ai/manifests.md), which are currently only supported for [React](https://storybook.js.org/docs/ai/?renderer=react.md) projects.

Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature.

Use Storybook together with an AI agent effectively by following these best practices.

## Writing effective stories

Stories are referenced by the [MCP server](https://storybook.js.org/docs/ai/mcp/overview.md) to provide examples of how your components are used. They are also tested to ensure your components work as expected. Whenever possible, they should demonstrate one concept or use case, and be as descriptive about the "why" behind the story, not just the "what". This will help agents understand when and why to use certain components or patterns.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;

type Story = StoryObj<typeof meta>;

// ✅ Good to show the default state
export const Basic: Story = {};

// ✅ Good to demonstrate a specific use case
export const Primary: Story = {
  args: { primary: true },
};

// ✅ Good - even though this story renders more than one button,
// they both demonstrate the same concept of a disabled button
export const Disabled: Story = {
  args: { disabled: true },
    render: (args) => (
      <>
      Disabled Button
      
        Disabled Primary Button
      
    </>
  ),
};

// ❌ Bad - demonstrates too many concepts at once, making
// it less clear and less useful as a reference for agents
export const SizesAndVariants: Story = {
  render: () => (
    <>
      Small Button
      Medium Button
      Large Button
      Outline Button
      Text Button
    </>
  ),
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

// ✅ Good to show the default state
export const Basic = meta.story();

// ✅ Good to demonstrate a specific use case
export const Primary = meta.story({
  args: { primary: true },
});

// ✅ Good - even though this story renders more than one button,
// they both demonstrate the same concept of a disabled button
export const Disabled = meta.story({
  args: { disabled: true },
  render: (args) => (
    <>
      Disabled Button
      
        Disabled Primary Button
      
    </>
  ),
});

// ❌ Bad - demonstrates too many concepts at once, making
// it less clear and less useful as a reference for agents
export const SizesAndVariants = meta.story({
  render: () => (
    <>
      Small Button
      Medium Button
      Large Button
      Outline Button
      Text Button
    </>
  ),
});
```

You might be wondering how well an agent handles abstractions like [`args`](https://storybook.js.org/docs/writing-stories/args.md) or [decorators](https://storybook.js.org/docs/writing-stories/decorators.md). The manifest generation process evaluates the final rendered story with all args, decorators, etc. applied, so it can focus on the concept being demonstrated, rather than the specifics of how it's implemented.

## Documenting your components

To reuse your components effectively, agents depend on how well you document their purpose, usage, and APIs. There are a few key aspects that are well worth taking the time to document (ask your agent to help!). To provide these details, you can use [JSDoc comments](https://jsdoc.app/about-getting-started) in your code, which Storybook will automatically extract and include in the generated [manifest](https://storybook.js.org/docs/ai/manifests.md) for the agent.

Of course, with [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md), any documentation efforts you make will help human developers, too!

### Component summary and description

Help the agent understand what a component should be used for by providing a description (and optional summary) as a JSDoc comment above the export of the component.

The agent will receive the summary, if present, or a truncated version of the description.

```ts title="Button.tsx"
/**
 * Button is used for user interactions that do not navigate to another route.
 * For navigation, use [Link](https://storybook.js.org/docs/ai/?path=/docs/link--default.md) instead.
 *
 * @summary for user interactions that do not navigate to another route
 */
export const Button = // ...
```

You can use Markdown syntax in your description to add formatting or links.

### Story summary and descriptions

Similarly, you can provide descriptions (and summaries) for each story, which serve as usage examples for the agent. Don't just repeat what the story is demonstrating; describe _why_ you would use whatever is demonstrated.

The agent will receive the summary, if present, or the first 60 characters of the description.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;

type Story = StoryObj<typeof meta>;

/**
 * Primary buttons are used for the main action in a view.
 * There should not be more than one primary button per view.
 *
 * @summary for the main action in a view
 */
export const Primary: Story = {
  args: { primary: true },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

/**
 * Primary buttons are used for the main action in a view.
 * There should not be more than one primary button per view.
 *
 * @summary for the main action in a view
 */
export const Primary = meta.story({
  args: { primary: true },
});
```

### Prop type extraction

We highly recommend using `react-docgen-typescript` for prop type extraction (set with the [`reactDocgen`](https://storybook.js.org/docs/api/main-config/main-config-typescript.md#reactdocgen) config option), because it provides more accurate and comprehensive information about your components' props, which will help agents use them more effectively. If manifest generation seems too slow, you can switch to `react-docgen`, which is faster but less detailed.

### Prop descriptions

It's also helpful to provide descriptions for your component's props in the JSDoc comments in your component code, as agents will use these to understand how to use the component effectively.

```ts title="Button.tsx"
export interface ButtonProps {
  /** The icon to render before the button text */
  icon?: ReactNode;
}
```

## Docs summaries

For unattached MDX docs pages (such as documentation for design tokens, guidelines, etc.), you can provide a summary in the `Meta` tag, which will be included in the manifest and provided to the agent.

```mdx title="Colors.mdx"

```

## Docs content

Storybook generates this docs manifest through static analysis of your MDX files, which means it is limited to the information that is explicitly present in those files. For example, the manifest will _not_ include the color tokens in the document below, because their values are not explicitly in the source:

```mdx title="Colors.mdx"

# Colors

  {colors.map((color) => (
    
  ))}

```

To ensure that your agents have access to all the necessary information, it's important to include any relevant details directly in your MDX files, rather than referencing external sources.

We hope to improve this in the future, possibly by evaluating the MDX files and including the result in the manifest.

## Manifest curation

It's possible to provide too little _or_ too much context to your agent. If your manifest is missing key information about your components, the agent may not be able to use them effectively. On the other hand, if your manifest includes information irrelevant to the task at hand, it may be overwhelming for the agent and lead to worse performance.

For stories or docs which the agent does not need to reference (e.g. a story demonstrating an anti-pattern or a docs page about deprecated components), you can exclude them from the manifest by removing the `manifest` [tag](https://storybook.js.org/docs/writing-stories/tags.md):

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;

type Story = StoryObj<typeof meta>;

// 👇 This story will be included in the manifest because it has the implicit 'manifest' tag
export const Basic = {};

export const ForInstructionOnly = {
  tags: ['!manifest'], // 👈 Remove the 'manifest' tag to exclude this story from the manifests
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

// 👇 This story will be included in the manifest because it has the implicit 'manifest' tag
export const Basic = meta.story();

export const ForInstructionOnly = meta.story({
  tags: ['!manifest'], // 👈 Remove the 'manifest' tag to exclude this story from the manifests
});
```

You can also remove an entire component from the manifest, by removing the tag in the meta (or default export) of the file, which will exclude all stories in that file from the manifests.

Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata:

```mdx title="DocForHumansOnly.mdx"

```

**More AI resources**

- [Agentic setup](https://storybook.js.org/docs/ai/setup.md)
- [MCP server overview](https://storybook.js.org/docs/ai/mcp/overview.md)
- [MCP server API](https://storybook.js.org/docs/ai/mcp/api.md)
- [Sharing your MCP server](https://storybook.js.org/docs/ai/mcp/sharing.md)
- [Manifests](https://storybook.js.org/docs/ai/manifests.md)
> Source: https://storybook.js.org/docs/ai/best-practices
---

# Manifests

While they are in [preview](https://storybook.js.org/docs/releases/features.md#preview), Storybook's AI capabilities (specifically, the manifests and [MCP server](https://storybook.js.org/docs/ai/mcp/overview.md)) are currently only supported for [React](https://storybook.js.org/docs/ai/?renderer=react.md) projects.

Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature.

Your Storybook holds a wealth of information about your components: their names, descriptions, API, usage examples, and more. Manifests are JSON objects that describe the contents of your Storybook in a concise, structured way that is easy for AI agents to understand and use. The manifests are generated automatically from your Storybook's CSF and MDX files, and they are designed to be comprehensive and up-to-date representations of your Storybook's contents.

There are two types of manifests generated by Storybook: components and docs.

## Components manifest

The components manifest is generated from static analysis of the CSF files in your Storybook and prop type extraction from their associated component source code. It contains information about the components you have documented, such as their names, descriptions, props, and usage examples. This manifest is designed to help AI agents understand which components are available and how to use them.

For prop type extraction, the manifest generation will use whatever is specified in the [`reactDocgen`](https://storybook.js.org/docs/api/main-config/main-config-typescript.md#reactdocgen) option, or `react-docgen` by default. We recommend using `react-docgen-typescript` for most projects, because it provides more accurate and comprehensive information about your components' props. If manifest generation seems too slow, you can switch to `react-docgen`, which is faster but less detailed.

While the types themselves provide a basic level of information, JSDoc comments in your component source code can provide additional metadata for the manifest, which can be helpful for AI agents. We highly recommend adding JSDoc comments to your components and their props to provide as much context as possible for the agents. For example:

```ts title="Button.tsx"

type ButtonProps = {
  /**
   * Optional click handler
   */
  onClick?: () => void;
};

/**
 * Button is used for user interactions that do not navigate to another route.
 * For navigation, use [Link](https://storybook.js.org/docs/ai/?path=/docs/link--default.md) instead.
 */
export const Button: React.FC<ButtonProps> = ({ onClick }) => {
  //...
};
```

Check the [best practices](https://storybook.js.org/docs/ai/best-practices.md) guide for tips on writing effective JSDoc comments for your components and other ways to provide helpful context for the agents.

If a story file declares [`subcomponents`](https://storybook.js.org/docs/writing-stories/stories-for-multiple-components.md#subcomponents), the components manifest will also include a `subcomponents` object for that component. This gives agents supplemental API documentation for child components, even when those subcomponents are only meant to be used together with the parent.

The raw JSON components manifest can be accessed at `http://localhost:6006/manifests/components.json` (your port may vary) when your Storybook is running or at the `/manifests/components.json` route in a built Storybook.

<details>
<summary>Example components manifest entry</summary>

While in [preview](https://storybook.js.org/docs/releases/features.md#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding.

```json
{
  "components": {
    "components-button": {
      "id": "components-button",
      "name": "Button",
      "path": "./src/components/Button/Button.stories.tsx",
      "stories": [
        {
          "id": "components-button--default",
          "name": "Default",
          "snippet": "const Default = () =\u003E \u003CButton\u003EButton\u003C/Button\u003E;"
        },
        {
          "id": "components-button--disabled",
          "name": "Disabled",
          "snippet": "const Disabled = () =\u003E \u003CButton disabled\u003EButton\u003C/Button\u003E;"
        }
      ],
      "import": "import { Button } from \"@mealdrop/ui\";",
      "jsDocTags": {},
      "description": "Primary UI component for user interaction",
      "reactDocgen": {
        "description": "Primary UI component for user interaction",
        "methods": [],
        "displayName": "Button",
        "definedInFile": "/path/to/project/src/components/Button/Button.tsx",
        "actualName": "Button",
        "exportName": "Button",
        "props": {
          "clear": {
            "required": false,
            "tsType": {
              "name": "boolean"
            },
            "description": "Clear button styles leaving just a text",
            "defaultValue": {
              "value": "false",
              "computed": false
            }
          },
          "round": {
            "required": false,
            "tsType": {
              "name": "boolean"
            },
            "description": "",
            "defaultValue": {
              "value": "false",
              "computed": false
            }
          },
          "large": {
            "required": false,
            "tsType": {
              "name": "boolean"
            },
            "description": "Is the button large?",
            "defaultValue": {
              "value": "false",
              "computed": false
            }
          },
          "icon": {
            "required": false,
            "tsType": {
              "name": "union",
              "raw": "| 'arrow-right'\n| 'arrow-left'\n| 'cross'\n| 'cart'\n| 'minus'\n| 'plus'\n| 'moon'\n| 'sun'\n| 'star'",
              "elements": [
                {
                  "name": "literal",
                  "value": "'arrow-right'"
                },
                {
                  "name": "literal",
                  "value": "'arrow-left'"
                },
                {
                  "name": "literal",
                  "value": "'cross'"
                },
                {
                  "name": "literal",
                  "value": "'cart'"
                },
                {
                  "name": "literal",
                  "value": "'minus'"
                },
                {
                  "name": "literal",
                  "value": "'plus'"
                },
                {
                  "name": "literal",
                  "value": "'moon'"
                },
                {
                  "name": "literal",
                  "value": "'sun'"
                },
                {
                  "name": "literal",
                  "value": "'star'"
                }
              ]
            },
            "description": "Does the button have an icon?"
          },
          "iconSize": {
            "required": false,
            "tsType": {
              "name": "number"
            },
            "description": "Size of the icon"
          },
          "disabled": {
            "required": false,
            "tsType": {
              "name": "boolean"
            },
            "description": "Is the button disabled?"
          },
          "children": {
            "required": false,
            "tsType": {
              "name": "union",
              "raw": "string | React.ReactNode",
              "elements": [
                {
                  "name": "string"
                },
                {
                  "name": "ReactReactNode",
                  "raw": "React.ReactNode"
                }
              ]
            },
            "description": "The content of the button"
          },
          "onClick": {
            "required": false,
            "tsType": {
              "name": "signature",
              "type": "function",
              "raw": "() =\u003E void",
              "signature": {
                "arguments": [],
                "return": {
                  "name": "void"
                }
              }
            },
            "description": "Optional click handler"
          }
        }
      }
    }
  }
}
```

</details>

## Docs (MDX) manifest

The docs manifest is generated from the [MDX files](https://storybook.js.org/docs/writing-docs/mdx.md) in your Storybook. These files are used to document specific components or to create standalone documentation pages (e.g. a "Getting Started" guide, accessibility guidelines, design tokens, etc.), all of which can offer helpful context to the agent.

The raw JSON docs manifest can be accessed at `http://localhost:6006/manifests/docs.json` (your port may vary) when your Storybook is running or at the `/manifests/docs.json` route in a built Storybook.

Check the [best practices](https://storybook.js.org/docs/ai/best-practices.md) guide for tips on writing effective documentation and providing helpful context for the agents.

<details>
<summary>Example docs manifest entry</summary>

While in [preview](https://storybook.js.org/docs/releases/features.md#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding.

```json
{
  "docs": {
    "design-system-typography--docs": {
      "id": "design-system-typography--docs",
      "name": "Docs",
      "path": "./src/docs/Typography.mdx",
      "title": "Design System/Typography",
      "content": "import { Meta, Typeset } from '@storybook/addon-docs/blocks'\n\n\u003CMeta title=\"Design System/Typography\" /\u003E\n\n# Typography\n\n## Font: Hind\n\nUsed for body texts, descriptions and general info\n\n**Weight:** 400(regular)\n\n\u003CTypeset\n  sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n  fontSizes={[12, 14, 18, 24]}\n  fontWeight={400}\n  fontFamily=\"Hind\"\n/\u003E\n\n**Weight:** 500(medium)\n\n\u003CTypeset\n  sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n  fontSizes={[12, 14, 18, 24]}\n  fontWeight={500}\n  fontFamily=\"Hind\"\n/\u003E\n\n## Font: Montserrat\n\nUsed for headings and titles\n\n**Weight:** 400 (regular)\n\n\u003CTypeset\n  sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n  fontSizes={[12, 14, 18, 24]}\n  fontWeight={400}\n  fontFamily=\"Montserrat\"\n/\u003E\n\n**Weight:** 500 (medium)\n\n\u003CTypeset\n  sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n  fontSizes={[12, 14, 18, 24]}\n  fontWeight={500}\n  fontFamily=\"Montserrat\"\n/\u003E\n\n**Weight:** 700 (bold)\n\n\u003CTypeset\n  sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n  fontSizes={[12, 14, 18, 24]}\n  fontWeight={700}\n  fontFamily=\"Montserrat\"\n/\u003E\n\n**Weight:** 900 (black)\n\n\u003CTypeset\n  sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n  fontSizes={[12, 14, 18, 24]}\n  fontWeight={900}\n  fontFamily=\"Montserrat\"\n/\u003E\n"
    }
  }
}
```

</details>

## Debugging

To help you get a better picture of what is and is not in the manifests, Storybook provides a combined manifest debugger at `http://localhost:6006/manifests/components.html` (your port may vary). This page shows the contents of both the component and docs manifests in a human-readable format, along with any errors or warnings that were encountered during manifest generation.

![Manifest debugger](../_assets/ai/manifest-debugger.png)

At the top of the page, you can see any errors or warnings that were encountered during manifest generation. You can click these buttons to filter the manifest to show only the relevant entries, which can be helpful for debugging.

## Curating

By default, all stories and independent docs pages have the `manifest` [tag](https://storybook.js.org/docs/writing-stories/tags.md) applied, which means they will be included in the manifests. You can curate what is included in the manifests by adding or removing the `manifest` tag from your stories and docs pages. For example, if you have a story that is for instructional purposes only and the agent should not be aware of it, you can remove the `manifest` tag from that story to exclude it from the manifests:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;

type Story = StoryObj<typeof meta>;

// 👇 This story will be included in the manifest because it has the implicit 'manifest' tag
export const Basic = {};

export const ForInstructionOnly = {
  tags: ['!manifest'], // 👈 Remove the 'manifest' tag to exclude this story from the manifests
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

// 👇 This story will be included in the manifest because it has the implicit 'manifest' tag
export const Basic = meta.story();

export const ForInstructionOnly = meta.story({
  tags: ['!manifest'], // 👈 Remove the 'manifest' tag to exclude this story from the manifests
});
```

You can also remove an entire component from the manifest by removing the tag in the file's meta (or default export), which will exclude all stories in that file from the manifests.

Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata:

```mdx title="DocForHumansOnly.mdx"

```

**More AI resources**

- [Agentic setup](https://storybook.js.org/docs/ai/setup.md)
- [MCP server overview](https://storybook.js.org/docs/ai/mcp/overview.md)
- [MCP server API](https://storybook.js.org/docs/ai/mcp/api.md)
- [Sharing your MCP server](https://storybook.js.org/docs/ai/mcp/sharing.md)
- [Best practices for using Storybook with AI](https://storybook.js.org/docs/ai/best-practices.md)
> Source: https://storybook.js.org/docs/ai/manifests
---

# Sharing

Once your components are built and tested, sharing your Storybook helps the rest of your team see how they work. You can publish your Storybook online, embed individual stories on other sites, integrate with design tools like Figma, or compose multiple Storybooks together.

## Quick sharing

The easiest way to share your Storybook is the Share button in the Storybook UI, which generates a link to your Storybook that you can share with anyone without needing to set up a hosting solution. Sharing is provided by Chromatic's [Visual Tests addon](https://storybook.js.org/addons/@chromatic-com/storybook).

![Share menu open, with title: Publish a build to share](../_assets/sharing/share-menu.png)

## Publish

If you need more control over how your Storybook is shared, you can build Storybook as a static web app and deploy it anywhere you host static sites. A published Storybook gives developers, designers, PMs, and other stakeholders a shared URL to review work in progress without a local dev environment. You can host it for free on [Chromatic](https://www.chromatic.com/features/publish?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) for review and visual testing workflows, or on services like GitHub Pages, Netlify, or AWS S3.

Read more in [Publish Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md).

## Embed

Once your Storybook is published and publicly accessible, you can embed individual stories in other pages. Storybook supports `<iframe>` embeds out of the box, and Storybooks published to Chromatic also work with the oEmbed standard, so stories render inline in Notion, Medium, and other oEmbed-compatible platforms.

Read more in [Embed stories](https://storybook.js.org/docs/sharing/embed.md).

## Design integrations

Storybook integrates with design tools to tighten the loop between design and implementation. Embed Storybook stories in Figma to compare designs against the real components, or embed Figma frames in Storybook to reference designs alongside the components that implement them.

Read more in [Design integrations](https://storybook.js.org/docs/sharing/design-integrations.md).

## Composition

Composition lets you browse components from any other Storybook—published or running locally—inside your own Storybook's sidebar. It works across renderers and tech stacks, which makes it useful for referencing a design system, auditing component usage across projects, or viewing multiple Storybooks in one place.

Design system and component library authors can [configure their package](https://storybook.js.org/docs/sharing/package-composition.md) so that consumers automatically see the library's stories alongside their own when they install it. That gives consumers usage documentation in context, without leaving their Storybook.

Read more in [Storybook Composition](https://storybook.js.org/docs/sharing/storybook-composition.md).
> Source: https://storybook.js.org/docs/sharing
---

# Publish Storybook

Teams publish Storybook online to review and collaborate on works in progress. That allows developers, designers, PMs, and other stakeholders to check if the UI looks right without touching code or requiring a local dev environment.

## Build Storybook as a static web application

First, we'll need to build Storybook as a static web application. The functionality is already built-in and pre-configured for most supported frameworks. Run the following command inside your project's root directory:

```shell
npm run build-storybook
```

```shell
pnpm run build-storybook
```

```shell
yarn build-storybook
```

You can provide additional flags to customize the command. Read more about the flag options [here](https://storybook.js.org/docs/api/cli-options.md).

Storybook will create a static web application capable of being served by any web server. Preview it locally by running the following command:

```shell
npx http-server ./path/to/build
```

```shell
pnpm dlx http-server ./path/to/build
```

### Customizing the build for performance

By default, Storybook's production build will encapsulate all stories and documentation into the production bundle. This is ideal for small projects but can cause performance issues for larger projects or when decreased build times are a priority (e.g., testing, CI/CD). If you need, you can customize the production build with the [`test` option](https://storybook.js.org/docs/api/main-config/main-config-build.md#test) in your `main.js|ts` configuration file and adjust your build script to enable the optimizations with the `--test` [flag](https://storybook.js.org/docs/api/cli-options.md#build).

```shell
npm run build-storybook -- --test
```

```shell
pnpm run build-storybook --test
```

```shell
yarn build-storybook --test
```

### Build Storybook for older browsers

The Storybook app's UI supports [modern browsers](https://storybook.js.org/docs/get-started/install.md#project-requirements). If you need to run the app in older, unsupported browsers, you can use the [`--preview-only` CLI flag](https://storybook.js.org/docs/api/cli-options.md#build) to build Storybook in "preview-only" mode. This skips building the Storybook manager (the UI surrounding your stories) and only builds the preview (the iframe that contains your stories). That makes your [Storybook builder](https://storybook.js.org/docs/builders.md) and its configuration solely responsible for which browsers are supported.

When in "preview-only" mode, the normal entry point, `/index.html`, will result in a 404, because the client-side router is not available. To work around this, start from the `/iframe.html` route and add the `?navigator=true` query parameter to the URL. This will render a basic, HTML-only sidebar inside the preview so that you can navigate to your stories. For example, you can access the preview at `http://localhost:6006/iframe.html?navigator=true` (you may need to update the port number).

This applies to both the [`build`](https://storybook.js.org/docs/api/cli-options.md#build) (for publishing) and [`dev`](https://storybook.js.org/docs/api/cli-options.md#dev) (for local development) commands.

## Publish Storybook with Chromatic

Once you've built your Storybook as a static web application, you can publish it to your web host. We recommend [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook), a free publishing service made for Storybook that documents, versions, and indexes your UI components securely in the cloud.

![Storybook publishing workflow](../_assets/sharing/workflow-publish.png)

To get started, sign up with your GitHub, GitLab, Bitbucket, or email and generate a unique _project-token_ for your project.

Next, install the [Chromatic CLI](https://www.npmjs.com/package/chromatic) package from npm:

```shell
npm install chromatic --save-dev
```

```shell
pnpm add --save-dev chromatic
```

```shell
yarn add --dev chromatic
```

Run the following command after the package finishes installing. Make sure that you replace `your-project-token` with your own project token.

```shell
npx chromatic --project-token=<your-project-token>
```

When Chromatic finishes, you should have successfully deployed your Storybook. Preview it by clicking the link provided (i.e., `https://random-uuid.chromatic.com`).

```shell
Build 1 published.

View it online at https://www.chromatic.com/build?appId=...&number=1.
```

![Chromatic publish build](../_assets/sharing/build-publish-only.png)

### Setup CI to publish automatically

Configure your CI environment to publish your Storybook and [run Chromatic](https://www.chromatic.com/docs/ci?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) whenever you push code to a repository. Let's see how to set it up using GitHub Actions.

In your project's root directory, add a new file called `chromatic.yml` inside the `.github/workflows` directory:

```yml
// .github/workflows/chromatic.yml
# Workflow name
name: 'Chromatic Publish'

# Event for the workflow
on: push

# List of jobs
jobs:
  test:
    # Operating System
    runs-on: ubuntu-latest
    # Job steps
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: 'yarn'
      - run: yarn
      #👇 Adds Chromatic as a step in the workflow
      - uses: chromaui/action@latest
        # Options required for Chromatic's GitHub Action
        with:
          #👇 Chromatic projectToken,
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          token: ${{ secrets.GITHUB_TOKEN }}
```

Secrets are secure environment variables provided by GitHub so that you don't need to hard code your `project-token`. Read the [official documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) to learn how to configure them.

Commit and push the file. Congratulations, you've successfully automated publishing your Storybook. Now whenever you open a PR you’ll get a handy link to your published Storybook in your PR checks.

![PR check publish](../_assets/sharing/prbadge-publish.png)

### Review with your team

Publishing Storybook as part of the development process makes it quick and easy to gather team feedback.

A common method to ask for review is to paste a link to the published Storybook in a pull request or Slack.

If you publish your Storybook to Chromatic, you can use the [UI Review](https://www.chromatic.com/features/publish?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) feature to automatically scan your PRs for new and updated stories. That makes it easy to identify what changed and give feedback.

![UI review in Chromatic](../_assets/sharing/workflow-uireview.png)

### Versioning and history

When you publish Storybook, you also get component history and versioning down to the commit. That's useful during implementation review for comparing components between branches/commits to past versions.

![Library history in Chromatic](../_assets/sharing/workflow-history-versioning.png)

## Publish Storybook to other services

Since Storybook is built as a static web application, you can also publish it to any web host, including [GitHub Pages](https://docs.github.com/en/pages), [Netlify](https://www.netlify.com/), [AWS S3](https://aws.amazon.com/s3/), and more. However, features such as [Composition](https://storybook.js.org/docs/sharing/storybook-composition.md), [embedding stories](https://storybook.js.org/docs/sharing/embed.md), history, versioning, and assets may require tighter integration with Storybook APIs and secure authentication. If you want to know more about headers, you can refer to the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deploying-build-artifacts). Additionally, if you want to learn about the Component Publishing Protocol (CPP), you can find more information below.

### GitHub Pages

To deploy Storybook on GitHub Pages, use the community-built [Deploy Storybook to GitHub Pages](https://github.com/bitovi/github-actions-storybook-to-github-pages) Action. To enable it, create a new workflow file inside your `.github/workflows` directory with the following content:

```yml
// .github/workflows/deploy-github-pages.yml
name: Build and Publish Storybook to GitHub Pages
on:
  push:
    branches:
      - 'your-branch-name' # Use specific branch name
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: 'pages'
  cancel-in-progress: false
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm' # Adjust caching strategy and configuration if using other package managers
      - name: Install dependencies
        run: npm ci # Replace with appropriate command if using other package managers
      - name: Build Storybook
        run: npm run build-storybook
      # Upload pages artifact
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'storybook-static'
      # Deploy to Github Pages
      - id: deploy
        name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4
        with:
          token: ${{ github.token }}
```

The GitHub Pages Action requires additional configuration options to customize the deployment process. Refer to the [official documentation](https://github.com/marketplace/actions/deploy-storybook-to-github-pages) for more information.

<details>
<summary>
<h3>Component Publishing Protocol (CPP)</h3>
</summary>

Storybook can communicate with services that host built Storybooks online. This enables features such as [Composition](https://storybook.js.org/docs/sharing/storybook-composition.md). We categorize services via compliance with the "Component Publishing Protocol" (CPP) with various levels of support in Storybook.

### CPP level 1

This level of service serves published Storybooks and makes the following available:

- Versioned endpoints, URLs that resolve to different published Storybooks depending on a `version=x.y.z` query parameter (where `x.y.z` is the released version of the package).
- Support for `/index.json` (formerly `/stories.json`) endpoint, which returns a list of stories and their metadata.
- Support for `/metadata.json` and the `releases` field.

Example: [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook)

### CPP level 0

This level of service can serve published Storybooks but has no further integration with Storybook’s APIs.

Examples: [Netlify](https://www.netlify.com/), [S3](https://aws.amazon.com/en/s3/)

</details>

## Search engine optimization (SEO)

If your Storybook is publicly viewable, you may wish to configure how it is represented in search engine result pages.

### Description

You can provide a description for search engines to display in the results listing, by adding the following to the `manager-head.html` file in your config directory:

```html
// .storybook/manager-head.html
<meta name="description" content="Components for my awesome project" key="desc" />
```

### Preventing your Storybook from being crawled

You can prevent your published Storybook from appearing in search engine results by including a noindex meta tag, which you can do by adding the following to the `manager-head.html` file in your config directory:

```html
// .storybook/manager-head.html
<meta name="robots" content="noindex" />
```
> Source: https://storybook.js.org/docs/sharing/publish-storybook
---

# Embed stories

Embed stories to showcase your work to teammates and the developer community at large. In order to use embeds, your Storybook must be published and publicly accessible.

Storybook supports `<iframe>` embeds out of the box. If you use Chromatic to [publish Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md#publish-storybook-with-chromatic), you can also embed stories in Notion, Medium, and countless other platforms that support the oEmbed standard.

## Embed a story with the toolbar

Embed a story with the toolbar, and paste the published story URL. For example:

```js
// oEmbed
// https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/?path=/story/shadowboxcta--default

// iframe embed
<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/?path=/story/shadowboxcta--default&full=1&shortcuts=false&singleStory=true"
  width="800"
  height="260"
></iframe>
```

<br />

<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/?path=/story/shadowboxcta--default&full=1&shortcuts=false&singleStory=true"
  width="800"
  height="260"
/>

## Embed a story without the toolbar

To embed a plain story without Storybook's toolbar, click the "open canvas in new tab" icon in the top-right corner of Storybook to get the canvas URL. For example:

```js
// oEmbed
// https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=/story/shadowboxcta--default&viewMode=story

// iframe embed
<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--default&viewMode=story&shortcuts=false&singleStory=true"
  width="800"
  height="200"
></iframe>
```

<br />

<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--default&viewMode=story&shortcuts=false&singleStory=true"
  width="800"
  height="200"
/>

## Embed documentation

Embed a documentation page by replacing `viewMode=story` with the uniquely auto-generated documentation entry for the story.

```js
// oEmbed
// https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--docs&viewMode=docs&shortcuts=false&singleStory=true

// iframe embed
<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--docs&viewMode=docs&shortcuts=false&singleStory=true"
  width="800"
  height="400"
></iframe>
```

<br />

<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--docs&viewMode=docs&shortcuts=false&singleStory=true"
  width="800"
  height="400"
/>

## Embed stories on other platforms

Every platform has different levels of embed support. Check the documentation of your service to see how they recommend embedding external content.

<details>
<summary>How to embed in Medium</summary>

Paste the Storybook URL into your Medium article, then press Enter. The embed will automatically resize to fit the story's height.

While editing an article, Medium renders all embeds non-interactive. Once your article is published, it will become interactive. [Preview a demo on Medium](https://medium.com/@ghengeveld/embedding-storybook-on-medium-ce8a280c03ad).

</details>

<details>
<summary>How to embed in Notion</summary>

In your Notion document, type /embed, press Enter, and paste the story URL as the embed link. You can resize the embed as necessary.

![Embed Notion](../_assets/sharing/embed-notion.png)

</details>

<details>
<summary>How to embed in Ghost</summary>

Type `/html` in your Ghost post, press Enter and paste the iframe URL. You can resize the embed via the width and height properties as required.

![Embed Ghost](../_assets/sharing/embed-ghost.png)

</details>
> Source: https://storybook.js.org/docs/sharing/embed
---

# Design integrations

Storybook integrates with design tools to speed up your development workflow. That helps you debug inconsistencies earlier in the design process, discover existing components to reuse, and compare designs to stories.

## Figma

[Figma](https://www.figma.com/) is a collaborative UI design tool that allows multiple people to work on the same design simultaneously in the browser. There are two ways to integrate Storybook and Figma.

- [**Embed Storybook in Figma**](#embed-storybook-in-figma-with-the-plugin)
- [**Embed Figma in Storybook**](#embed-figma-in-storybook-with-the-addon)

### Embed Storybook in Figma with the plugin

[Storybook Connect](https://www.figma.com/community/plugin/1056265616080331589/Storybook-Connect) is a Figma plugin that allows you to embed component stories in Figma. It’s powered by [Storybook embeds](https://storybook.js.org/docs/sharing/embed.md) and [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook), a publishing tool created by the Storybook team.

#### Install plugin

Before we begin, you must have a Storybook [published to Chromatic](https://storybook.js.org/docs/sharing/publish-storybook.md#publish-storybook-with-chromatic). It provides the index, versions, and access control that back the plugin.

Go to [Storybook Connect](https://www.figma.com/community/plugin/1056265616080331589/Storybook-Connect) to install the plugin.

In Figma, open the command palette (in Mac OS, use `Command + /`, in Windows use `Control + /`) and type `Storybook Connect` to enable it.

![Figma palette Storybook connect](../_assets/sharing/figma-plugin-open-in-figma.png)

Follow the instructions to connect and authenticate with Chromatic.

#### Link stories to Figma components

Link stories to Figma components, variants, and instances.

Go to a story in a Storybook published on Chromatic. Make sure it’s on the branch you want to link. Then copy the URL to the story.

In Figma, select the component, open the plugin, and paste the URL.

![Story linked in Figma](../_assets/sharing/figma-plugin-paste-url.png)

Chromatic will automatically update your linked stories to reflect the most recent Storybook published on the branch you linked. That means the link persists even as you push new code.

The plugin does not support linking stories to Figma layers.

#### View stories in Figma

Once they're connected, you'll be able to view the story by clicking the link in the sidebar. Click "View story". Alternatively, open the plugin by using the command palette (in Mac OS, use `Command + /`, in Windows, use `Control + /`), then type `Storybook Connect`.

![Figma sidebar with story link](../_assets/sharing/figma-plugin-sidebar.png)

### Embed Figma in Storybook with the addon

[Designs addon](https://storybook.js.org/addons/@storybook/addon-designs) allows you to embed Figma files and prototypes in Storybook.

![Storybook addon figma](../_assets/sharing/storybook-figma-addon.png)

#### Install design addon

Run the following command to install the addon.

```shell
npx storybook@latest add @storybook/addon-designs
```

```shell
pnpm dlx storybook@latest add @storybook/addon-designs
```

```shell
yarn dlx storybook@latest add @storybook/addon-designs
```

The CLI's [`add`](https://storybook.js.org/docs/api/cli-options.md#add) command automates the addon's installation and setup. To install it manually, see our [documentation](https://storybook.js.org/docs/addons/install-addons.md#manual-installation) on how to install addons.

#### Link Figma components to stories

In Figma, open the file you want to embed in Storybook. You can embed files, prototypes, components, and frames.

- Embed a file or prototype, click the "Share" button to generate a unique URL for the file then click "Copy link".

- Embed a component or frame check "Link to selected frame" in the Share dialog. Or right click on the frame and go to "Copy/Paste as" » "Copy link".

In Storybook, add a new [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) named `design` to your story and paste the Figma URL. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// More on default export: https://storybook.js.org/docs/writing-stories/#default-export
const meta = {
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;

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

export const Example: Story = {
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/Sample-File',
    },
  },
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

// More on default export: https://storybook.js.org/docs/writing-stories/#default-export
const meta = preview.meta({
  component: MyComponent,
});

export const Example = meta.story({
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/Sample-File',
    },
  },
});
```

#### View designs in Storybook

Click the "Design" tab in the addon panel to view the embedded Figma design.

![Design addon panel](../_assets/sharing/design-addon-panel.png)

## Zeplin

[Zeplin](https://zeplin.io/) is a design tool that generates styleguides from [Sketch](https://www.sketch.com/), [Figma](https://www.figma.com/), and [Adobe XD](https://www.adobe.com/products/xd.html).

Use the [Zeplin addon](https://storybook.js.org/addons/storybook-zeplin) to connect Storybook. The addon displays designs from Zeplin alongside the currently selected story. It includes convenient tooling to overlay the design image atop the live component.

Zeplin's native app also supports [links to published Storybooks](https://support.zeplin.io/en/articles/5674596-connecting-your-storybook-instance-with-zeplin).

![Zeplin Storybook addon](../_assets/sharing/storybook-zeplin-addon.png)

## Zeroheight

[Zeroheight](https://zeroheight.com/) is a collaborative styleguide generator for design systems. It showcases design, code, brand, and copywriting documentation in one place. Users can edit that documentation with a WYSIWYG editor.

Zeroheight integrates with [Storybook](https://zeroheight.com/3xlwst8/p/507ba7-storybook), enabling you to embed stories alongside your design specs.

![Zeroheight Storybook integration](../_assets/sharing/storybook-zeroheight.gif)

## UXPin

[UXPin](https://www.uxpin.com/) is an interactive design tool that uses production code to generate prototypes.

UXPin allows you to [use interactive stories](https://www.uxpin.com/docs/merge/storybook-integration/) to design user flows.

## InVision Design System Manager

[InVision DSM](https://www.invisionapp.com/design-system-manager) is a design system documentation tool. It helps design teams consolidate UX principles, user interface design, and design tokens in a shared workspace.

InVision allows you to embed [Storybook](https://support.invisionapp.com/hc/en-us/articles/360028388192-Publishing-Storybook-to-DSM) in your design system documentation.

![Invision DSM Storybook integration](../_assets/sharing/storybook-invision-dsm.gif)

## Adobe XD

[Adobe XD](https://www.adobe.com/products/xd.html) is a UI and UX design tool for creating wireframes, interactive designs, and prototypes.

Integrate Adobe XD with Storybook using the [design addon](https://storybook.js.org/addons/storybook-addon-designs/). You can [embed design specs](https://helpx.adobe.com/xd/help/publish-design-specs.html) alongside stories by following these [instructions](https://pocka.github.io/storybook-addon-designs/?path=/story/docs-iframe-readme--page).

## Build your own integration

Extend and customize Storybook by building an integration. Integrate with lower-level Storybook APIs or bootstrap an addon to customize Storybook's UI and behavior.

- [Addon documentation](https://storybook.js.org/docs/addons.md)
- [Create an addon tutorial](https://storybook.js.org/docs/addons/writing-addons.md)
> Source: https://storybook.js.org/docs/sharing/design-integrations
---

# Storybook Composition

Composition allows you to browse components from any Storybook accessible via URL inside your local Storybook. You can compose any [Storybook published online](https://storybook.js.org/docs/sharing/publish-storybook.md) or running locally no matter the view layer, tech stack, or dependencies.

![Storybook reference external](../_assets/sharing/reference-external-storybooks-composition.png)

You’ll see the composed Storybook’s stories in the sidebar alongside your own. This unlocks common workflows that teams often struggle with:

- 👩‍💻 UI developers can quickly reference prior art without switching between Storybooks.
- 🎨 Design systems can expand adoption by composing themselves into their users’ Storybooks.
- 🛠 Frontend platform can audit how components are used across projects.
- 📚 View multiple Storybooks with different tech stacks in one place

![Storybook composition](../_assets/sharing/combine-storybooks.png)

## Compose published Storybooks

In your [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file add a `refs` field with information about the reference Storybook. Pass in a URL to a statically built Storybook.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'design-system': {
      title: 'Storybook Design System',
      url: 'https://master--5ccbc373887ca40020446347.chromatic.com/',
      expanded: false, // Optional, true by default,
      sourceUrl: 'https://github.com/storybookjs/storybook', // Optional
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'design-system': {
      title: 'Storybook Design System',
      url: 'https://master--5ccbc373887ca40020446347.chromatic.com/',
      expanded: false, // Optional, true by default,
      sourceUrl: 'https://github.com/storybookjs/storybook', // Optional
    },
  },
});
```

Addons in composed Storybooks will not work as they normally do in a non-composed Storybook.

## Compose local Storybooks

You can also compose multiple Storybooks that are running locally. For instance, if you have a React Storybook and an Angular Storybook running on different ports, you can update your configuration file (i.e., `.storybook/main.js|ts`) and reference them as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    react: {
      title: 'React',
      url: 'http://localhost:7007',
    },
    angular: {
      title: 'Angular',
      url: 'http://localhost:7008',
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    react: {
      title: 'React',
      url: 'http://localhost:7007',
    },
    angular: {
      title: 'Angular',
      url: 'http://localhost:7008',
    },
  },
});
```

Adding this configuration will combine React and Angular Storybooks into your current one. You’ll see the changes being applied automatically when either of these changes. Enabling you to develop both frameworks in sync.

## Compose Storybooks per environment

You can also compose Storybooks based on the current development environment (e.g., development, staging, production). For instance, if the project you're working on already has a published Storybook but also includes a version with cutting-edge features not yet released, you can adjust the composition based on that. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // 👇 Retrieve the current environment from the configType argument
  refs: (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      return {
        react: {
          title: 'Composed React Storybook running in development mode',
          url: 'http://localhost:7007',
        },
        angular: {
          title: 'Composed Angular Storybook running in development mode',
          url: 'http://localhost:7008',
        },
      };
    }
    return {
      react: {
        title: 'Composed React Storybook running in production',
        url: 'https://your-production-react-storybook-url',
      },
      angular: {
        title: 'Composed Angular Storybook running in production',
        url: 'https://your-production-angular-storybook-url',
      },
    };
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // 👇 Retrieve the current environment from the configType argument
  refs: (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      return {
        react: {
          title: 'Composed React Storybook running in development mode',
          url: 'http://localhost:7007',
        },
        angular: {
          title: 'Composed Angular Storybook running in development mode',
          url: 'http://localhost:7008',
        },
      };
    }
    return {
      react: {
        title: 'Composed React Storybook running in production',
        url: 'https://your-production-react-storybook-url',
      },
      angular: {
        title: 'Composed Angular Storybook running in production',
        url: 'https://your-production-angular-storybook-url',
      },
    };
  },
});
```

Similar to other fields available in Storybook’s configuration file, the `refs` field can also be a function that accepts a `config` parameter containing Storybook’s configuration object. See the [API reference](https://storybook.js.org/docs/api/main-config/main-config-refs.md) for more information.

## Troubleshooting

### Storybook composition is not working with my project

If you're working with an outdated Storybook version or have a project-specific requirement that prevents you from updating your Storybook to the latest version, you can rely on the Storybook CLI to generate the `index.json` file when you deploy your Storybook. For example:

```shell
npx storybook@7.5.3 extract
```

```shell
pnpm dlx storybook@7.5.3 extract
```

```shell
yarn dlx storybook@7.5.3 extract
```

The usage of a specific version of the CLI is intended as the `extract` command is not available in Storybook 8.0 or higher. It also requires you to provide additional configuration to generate the `index.json` file accurately. See the [previous documentation](https://storybook.js.org/docs/7/sharing/storybook-composition.md) for more information.
> Source: https://storybook.js.org/docs/sharing/storybook-composition
---

# Package Composition

Storybook is widely used by component libraries and design systems. Design system authors can automatically compose their design systems inside their consumer’s Storybooks.

For example, if you use a design system package, its stories can appear alongside your own. That makes it convenient to cross reference usage documentation without leaving Storybook.

Composition via a package requires a secure integration between the service where you publish Storybook and Storybook’s own APIs. We recommend [publishing Storybook to Chromatic](https://storybook.js.org/docs/sharing/publish-storybook.md#publish-storybook-with-chromatic) for full support of these features.

## For consumers

Composition happens automatically if the package [supports](#for-authors) it. When you install the package, Storybook will load its stories alongside your own.

![Package composition workflow](../_assets/sharing/package-composition.png)

### Set up

If you want to configure how the composed Storybook behaves, you can disable the `ref` element in your [`.storybook/main.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering)

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'package-name': { disable: true },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'package-name': { disable: true },
  },
});
```

### Switching versions

Change the version of the composed Storybook to see how the library evolves. This requires [configuration](#show-a-version-selector) from the package author.

![Package composition workflow](../_assets/sharing/composition-versioning.png)

## For authors

Component library authors can expand adoption by composing their components in their consumer’s Storybooks.

Add a `storybook` property in your published `package.json` that contains an object with a `url` field. Point the URL field to a published Storybook at the version you want.

```json title="package.json"
{
  "storybook": {
    "url": "https://host.com/your-storybook-for-this-version"
  }
}
```

### Automatic version selection

If you're using [Chromatic](https://storybook.js.org/docs/sharing/publish-storybook.md#publish-storybook-with-chromatic), you can provide a single URL for your Storybook in the `storybook.url` field. You do not need to change the URL each time you publish a new version. Storybook will automatically find the correct URL for your package. For example:

```json title="package.json"
{
  "storybook": {
    "url": "https://master--xyz123.chromatic.com"
  }
}
```

In this example `xyz123` is your Chromatic project id. Storybook will automatically compose in the Storybook published to that project corresponding to the version the user has installed.

### Show a version selector

If you're using [Chromatic](https://storybook.js.org/docs/sharing/publish-storybook.md#publish-storybook-with-chromatic), you can provide a list of versions for the user to [choose from](#switching-versions) to experiment with other versions of your package.
> Source: https://storybook.js.org/docs/sharing/package-composition
---

# Essentials

Storybook essentials is a set of tools that help you build, test, and document your components within Storybook. It includes the following:

- [Actions](https://storybook.js.org/docs/essentials/actions.md)
- [Backgrounds](https://storybook.js.org/docs/essentials/backgrounds.md)
- [Controls](https://storybook.js.org/docs/essentials/controls.md)
- [Highlight](https://storybook.js.org/docs/essentials/highlight.md)
- [Measure & outline](https://storybook.js.org/docs/essentials/measure-and-outline.md)
- [Toolbars & globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md)
- [Viewport](https://storybook.js.org/docs/essentials/viewport.md)

## Configuration

Essentials is “zero-config”. It comes with a recommended configuration out of the box.

Many of the features above can be configured via [parameters](https://storybook.js.org/docs/writing-stories/parameters.md). See each feature's documentation (linked above) for more details.

## Disabling features

If you need to disable any of the essential features, you can do it by changing your [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure/index.md#configure-your-storybook-project) file.

For example, if you wanted to disable the [backgrounds feature](https://storybook.js.org/docs/essentials/backgrounds.md), you would apply the following change to your Storybook configuration:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    backgrounds: false, // 👈 disable the backgrounds feature
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    backgrounds: false, // 👈 disable the backgrounds feature
  },
});
```

You can use the following keys for each individual feature: `actions`, `backgrounds`, `controls`, `highlight`, `measure`, `outline`, `toolbars`, and `viewport`.
> Source: https://storybook.js.org/docs/essentials
---

# Actions

Actions are used to show that an event handler (callback) has been called, and to display its arguments. The actions panel can show both story args and other function calls.

## Story args

Actions work via supplying special Storybook-generated mock functions to your story's event handler args. There are two ways to get an action arg:

### Via `storybook/test` `fn` spies

The recommended way is to assign `fn()` to an arg, which creates a mock function that is automatically spied on by Storybook. This is very useful for writing [interaction tests](https://storybook.js.org/docs/writing-tests/interaction-testing.md).

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  // 👇 Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked
  args: { onClick: fn() },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  // 👇 Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked
  args: { onClick: fn() },
});
```

When your component calls an arg (because of either the user's interaction or the `play` function) with an `fn()` assignment, the event will show up in the actions panel:

![Actions usage](../_assets/essentials/addon-actions-screenshot.png)

If you are defining a mock function with `fn()` outside of `args`, you must provide a name for it to automatically log to the actions panel:

```js
const handleClick = fn().mockName('handleClick');
```

### Automatically matching args

Another option is to use a global parameter to match all [argTypes](https://storybook.js.org/docs/api/arg-types.md) that match a certain pattern. The following configuration automatically creates actions for each `on` argType (which you can either specify manually or can be [inferred automatically](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference)).

This is quite useful when your component has dozens (or hundreds) of methods and you do not want to manually apply the `fn` utility for each of those methods. However, **this is not the recommended** way of writing actions. That's because automatically inferred args **are not available as spies in your play function**. If you use `argTypesRegex` and your stories have play functions, you will need to also define args with the `fn` utility to test them in your play function.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on.*' },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    actions: { argTypesRegex: '^on.*' },
  },
});
```

If you need more granular control over which `argTypes` are matched, you can adjust your stories and include the `argTypesRegex` parameter. For example:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  parameters: { actions: { argTypesRegex: '^on.*' } },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: { actions: { argTypesRegex: '^on.*' } },
});
```

This will bind a standard HTML event handler to the outermost HTML element rendered by your component and trigger an action when the event is called for a given selector. The format is `<eventname> <selector>`. The selector is optional; it defaults to all elements.

## Non-story function calls

You can still use the actions panel if you need to log function calls that are unrelated to any story. This can be helpful for debugging or logging purposes. There are two main ways to do this: `spyOn` from `storybook/test` or the `action` function from `storybook/actions`. For basic logging, we recommend creating a function spy, and for more complex scenarios, you can use the `action` function directly.

### Via `storybook/test` `spyOn`

Mocks and spies from `storybook/test` are automatically logged as actions (when [applied as `arg` values or when given a name](#via-storybooktest-fn-spies)). The easiest way to show function calls in the actions panel is to use the `spyOn` utility function. Spies appear with a default name, which you can customize by calling the `mockName` method.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, svelte)

const preview: Preview = {
  async beforeEach() {
    spyOn(console, 'log').mockName('console.log');
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  async beforeEach() {
    spyOn(console, 'log').mockName('console.log');
  },
});
```

### Via the `action` function

To filter which function calls are logged, you can override the `spyOn` function's behavior by providing a custom implementation that calls the `action` function from `storybook/actions` only if it matches a specific condition to prevent it from logging all calls to the function it spies on.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, svelte)

const originalConsoleLog = console.log;
const preview: Preview = {
  async beforeEach() {
    spyOn(console, 'log')
      // Disable automatic logging in the actions panel
      .mockName('')
      .mockImplementation((args) => {
        // Check if the log message matches a certain pattern
        if (someCondition(args)) {
          // Manually log an action
          action('console.log')(args);
        }

        // Call the original console.log function
        originalConsoleLog(...args);
      });
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const originalConsoleLog = console.log;

export default definePreview({
  async beforeEach() {
    spyOn(console, 'log')
      // Disable automatic logging in the actions panel
      .mockName('')
      .mockImplementation((args) => {
        // Check if the log message matches a certain pattern
        if (someCondition(args)) {
          // Manually log an action
          action('console.log')(args);
        }

        // Call the original console.log function
        originalConsoleLog(...args);
      });
  },
});
```

## API

### Parameters

This contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `actions` namespace:

#### `argTypesRegex`

Type: `string`

Create actions for each arg that matches the regex. Please note the significant [limitations of this approach](#automatically-matching-args), as described above.

#### `disable`

Type: `boolean`

Disable the action panel.

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could then be re-enabled by setting it to `false` at the meta (component) or story level.

#### `expandLevel`

Type: `number`

Default: `1`

Controls how many levels deep the action tree is initially expanded. Useful when action arguments contain nested objects and you want to see more detail by default.

### Exports

```js

```

#### `action`

Type: `(name?: string) => void`

Allows you to create an action that appears in the actions panel of the Storybook UI when clicked. The action function takes an optional name parameter, which is used to identify the action in the UI.

```ts
// Button.stories.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  args: {
    // 👇 Create an action that appears when the onClick event is fired
    onClick: action('on-click'),
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  args: {
    // 👇 Create an action that appears when the onClick event is fired
    onClick: action('on-click'),
  },
});
```

#### `configureActions`

```js

```

Type: `(options?: ActionOptions) => void`

Configures the global behavior of the actions addon. Call this in your `.storybook/preview.*` file or anywhere before actions are used. Available options:

- **`limit`** (`number`, default: `50`): Maximum number of action entries to display. When the limit is reached, the oldest actions are discarded.
- **`clearOnStoryChange`** (`boolean`, default: `true`): Clear the actions panel when navigating to a different story.
- **`depth`** (`number`, default: `10`): Serialization depth for action arguments.

```js title=".storybook/preview.ts|tsx"

configureActions({
  limit: 20,
  clearOnStoryChange: false,
});
```
> Source: https://storybook.js.org/docs/essentials/actions
---

# Backgrounds

The backgrounds feature allows you to set the background color on which the story renders in the UI:

![Storybook with available backgrounds visible](../_assets/essentials/addon-backgrounds.png)

## Configuration

By default, the backgrounds feature includes a light and dark background.

But you're not restricted to these backgrounds. You can configure your own set of colors with the `backgrounds` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in your [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering).

You can define the available background colors using the [`options` property](#options) and set the initial background color using the `initialGlobals` property:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    backgrounds: {
      options: {
        // 👇 Default options
        dark: { name: 'Dark', value: '#333' },
        light: { name: 'Light', value: '#F7F9F2' },
        // 👇 Add your own
        maroon: { name: 'Maroon', value: '#400' },
      },
    },
  },
  initialGlobals: {
    // 👇 Set the initial background color
    backgrounds: { value: 'light' },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    backgrounds: {
      options: {
        // 👇 Default options
        dark: { name: 'Dark', value: '#333' },
        light: { name: 'Light', value: '#F7F9F2' },
        // 👇 Add your own
        maroon: { name: 'Maroon', value: '#400' },
      },
    },
  },
  initialGlobals: {
    // 👇 Set the initial background color
    backgrounds: { value: 'light' },
  },
});
```

## Defining the background for a story

The backgrounds feature enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can set a story to default to a specific background color, by using the `globals` option:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework (e.g., react-vite, vue3-vite, etc.)

const meta = {
  component: Button,
  globals: {
    // 👇 Set background value for all component stories
    backgrounds: { value: 'gray', grid: false },
  },
} satisfies Meta<typeof Button>;

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

export const OnDark: Story = {
  globals: {
    // 👇 Override background value for this story
    backgrounds: { value: 'dark' },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  globals: {
    // 👇 Set background value for all component stories
    backgrounds: { value: 'gray', grid: false },
  },
});

export const OnDark = meta.story({
  globals: {
    // 👇 Override background value for this story
    backgrounds: { value: 'dark' },
  },
});
```

When you specify a background color for a story (or a component's stories) using `globals`, the color is applied and cannot be changed using the toolbar. This is useful to ensure a story is always rendered on a specific background color.

## Extending the configuration

You can also configure backgrounds on a per-component or per-story basis through [parameter inheritance](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters).

To set the available background colors, use the [`options` property](#options). In this example, we'll adjust the colors for all of the Button component's stories:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: Button,
  parameters: {
    backgrounds: {
      options: {
        // 👇 Override the default `dark` option
        dark: { name: 'Dark', value: '#000' },
        // 👇 Add a new option
        gray: { name: 'Gray', value: '#CCC' },
      },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    backgrounds: {
      options: {
        // 👇 Override the default `dark` option
        dark: { name: 'Dark', value: '#000' },
        // 👇 Add a new option
        gray: { name: 'Gray', value: '#CCC' },
      },
    },
  },
});
```

## Disable backgrounds

If you want to turn off backgrounds in a story, you can do so by configuring the `backgrounds` parameter like so:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Large: Story = {
  parameters: {
    backgrounds: { disable: true },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Large = meta.story({
  parameters: {
    backgrounds: { disable: true },
  },
});
```

## Grid

The backgrounds feature also includes a Grid selector, which allows you to quickly see if your components are aligned.

You don't need additional configuration to get started. But its properties are fully customizable; if you don't supply any value to any of its properties, they'll default to the following values:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// To apply a set of backgrounds to all stories of Button:
const meta = {
  component: Button,
  parameters: {
    backgrounds: {
      grid: {
        cellSize: 20,
        opacity: 0.5,
        cellAmount: 5,
        offsetX: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
        offsetY: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
      },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

// To apply a set of backgrounds to all stories of Button:
const meta = preview.meta({
  component: Button,
  parameters: {
    backgrounds: {
      grid: {
        cellSize: 20,
        opacity: 0.5,
        cellAmount: 5,
        offsetX: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
        offsetY: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
      },
    },
  },
});
```

## API

### Globals

This module contributes the following globals to Storybook, under the `backgrounds` namespace:

#### `grid`

Type: `boolean`

Whether the [grid](#grid) is displayed.

#### `value`

Type: `string`

When set, the background color is applied and cannot be changed using the toolbar. Must match the key of one of the [available colors](#options).

### Parameters

This module contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `backgrounds` namespace:

#### `disable`

Type: `boolean`

Disable this feature's behavior. If you wish to disable this feature for the entire Storybook, you should [do so in your main configuration file](https://storybook.js.org/docs/essentials/index.md#disabling-features).

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could then be re-enabled by setting it to `false` at the meta (component) or story level.

#### `grid`

Type:

```ts
{
  cellAmount?: number;
  cellSize?: number;
  disable?: boolean;
  offsetX?: number;
  offsetY?: number;
  opacity?: number;
}
```

Configuration for the [background grid](#grid).

##### `grid.cellAmount`

Type: `number`

Default: `5`

Specify the size of the minor grid lines.

##### `grid.cellSize`

Type: `number`

Default: `20`

Specify the size of the major grid lines.

##### `grid.disable`

Type: `boolean`

Turn off the grid.

##### `grid.offsetX`

Type: `number`

Default: `0` if [story layout](https://storybook.js.org/docs/api/parameters.md#layout) is `'fullscreen'`; `16` if story layout is `'padded'`

Horizontal offset of the grid.

##### `grid.offsetY`

Type: `number`

Default: `0` if [story layout](https://storybook.js.org/docs/api/parameters.md#layout) is `'fullscreen'`; `16` if story layout is `'padded'`

Vertical offset of the grid.

##### `grid.opacity`

Type: `number`

Default: `0.5`

The opacity of the grid lines.

#### `options`

(Required, see description)

Type:

```ts
{
  [key: string]: {
    name: string;
    value: string;
  };
}
```

Available background colors. See above for a [usage example](#configuration).
> Source: https://storybook.js.org/docs/essentials/backgrounds
---

# Controls

Storybook Controls gives you a graphical UI to interact with a component's arguments dynamically without needing to code. Use the Controls panel to edit the inputs to your stories and see the results in real-time. It's a great way to explore your components and test different states.

Controls do not require any modification to your components. Stories for controls are:

- Convenient. Auto-generate controls based on React/Vue/Angular/etc. components.
- Portable. Reuse your interactive stories in documentation, tests, and even in designs.
- Rich. Customize the controls and interactive data to suit your exact needs.

To use Controls, you need to write your stories using [args](https://storybook.js.org/docs/writing-stories/args.md). Storybook will automatically generate UI controls based on your args and what it can infer about your component. Still, you can configure the controls further using [argTypes](https://storybook.js.org/docs/api/arg-types.md), see below.

If you have stories in the older pre-Storybook 6 style, check the [args & controls migration guide](https://medium.com/storybookjs/storybook-6-migration-guide-200346241bb5) to learn how to convert your existing stories for args.

## Choosing the control type

By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the meta (or default export) of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](https://storybook.js.org/docs/api/arg-types.md) for your component using [`react-docgen`](https://github.com/reactjs/react-docgen), a documentation generator for React components that also includes first-class support for TypeScript.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});
```

By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the meta (or default export) of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](https://storybook.js.org/docs/api/arg-types.md) for your component provided by the framework you've chosen to use.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});
```

If you're using a framework that doesn't support this feature, you'll need to define the `argTypes` for your component [manually](#fully-custom-args).

For instance, suppose you have a `variant` arg on your story that should be `primary` or `secondary`:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Primary: Story = {
  args: {
    variant: 'primary',
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  args: {
    variant: 'primary',
  },
});
```

By default, Storybook will render a free text input for the `variant` arg:

![Control using a string](../_assets/essentials/addon-controls-args-variant-string.png)

It works as long as you type a valid string into the auto-generated text control. Still, it's not the best UI for our scenario, given that the component only accepts `primary` or `secondary` as variants. Let’s replace it with Storybook’s radio component.

We can specify which controls get used by declaring a custom [argType](https://storybook.js.org/docs/api/arg-types.md) for the `variant` property. ArgTypes encode basic metadata for args, such as name, description, and defaultValue for an arg. These get automatically filled in by Storybook Docs.

`ArgTypes` can also contain arbitrary annotations, which the user can override. Since `variant` is a component property, let's put that annotation on the meta (or default export).

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  argTypes: {
    variant: {
      options: ['primary', 'secondary'],
      control: { type: 'radio' },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  argTypes: {
    variant: {
      options: ['primary', 'secondary'],
      control: { type: 'radio' },
    },
  },
});
```

ArgTypes are a powerful feature that can be used to customize the controls for your stories. For more information, see the documentation about [customizing controls](#annotation) with `argTypes` annotation.

This replaces the input with a radio group for a more intuitive experience.

![Control with a radio group](../_assets/essentials/addon-controls-args-variant-optimized.png)

## Custom control type matchers

Controls can automatically be inferred from arg's name with [regex](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp), but currently only for the color picker and date picker controls. If you've used the Storybook CLI to setup your project, it should have automatically created the following defaults in `.storybook/preview.ts|tsx`:

| Control   | Default regex                            | Description                                               |
| --------- | ---------------------------------------- | --------------------------------------------------------- |
| **color** | <code>{`/(background\|color)$/i`}</code> | Will display a color picker UI for the args that match it |
| **date**  | `/Date$/`                                | Will display a date picker UI for the args that match it  |

If you haven't used the CLI to set the configuration, or if you want to define your patterns, use the `matchers` property in the `controls` parameter:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
});
```

## Fully custom args

Until now, we only used auto-generated controls based on the component for which we're writing stories. If we are writing [complex stories](https://storybook.js.org/docs/writing-stories/stories-for-multiple-components.md), we may want to add controls for args that aren’t part of the component. For example, here's how you could use a `footer` arg to populate a child component:

```tsx
// Page.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & { footer?: string };

const meta = {
  component: Page,
  render: ({ footer, ...args }) => (
    
      <footer>{footer}</footer>
    
  ),
} satisfies Meta;
export default meta;

type Story = StoryObj<typeof meta>;

export const CustomFooter = {
  args: {
    footer: 'Built with Storybook',
  },
} satisfies Story;
```

```tsx
// Page.stories.ts|tsx — CSF Next 🧪

type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & {
  footer?: string;
};

const meta = preview.type<{ args: PagePropsAndCustomArgs }>().meta({
  component: Page,
  render: ({ footer, ...args }) => (
    <Page {...args}>
      <footer>{footer}</footer>
    
  ),
});

export const CustomFooter = meta.story({
  args: {
    footer: 'Built with Storybook',
  },
});
```

By default, Storybook will add controls for all args that:

- It infers from the component definition [if your framework supports it](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md).

- Appear in the list of args for your story.

Using `argTypes`, you can change the display and behavior of each control.

### Dealing with complex values

When dealing with non-primitive values, you'll notice that you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deep link to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., the Controls panel) and the preview (your story).

One way to deal with this is to use primitive values (e.g., strings) as arg values and add a custom `render` function to convert them to their complex counterpart before rendering. It isn't the nicest way to do it (see below), but certainly the most flexible.

```tsx
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: YourComponent,
  //👇 Creates specific argTypes with options
  argTypes: {
    propertyA: {
      options: ['Item One', 'Item Two', 'Item Three'],
      control: { type: 'select' }, // Automatically inferred when 'options' is defined
    },
    propertyB: {
      options: ['Another Item One', 'Another Item Two', 'Another Item Three'],
    },
  },
} satisfies Meta<typeof YourComponent>;

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

const someFunction = (valuePropertyA, valuePropertyB) => {
  // Do some logic here
};

export const ExampleStory: Story = {
  render: (args) => {
    const { propertyA, propertyB } = args;
    //👇 Assigns the function result to a variable
    const someFunctionResult = someFunction(propertyA, propertyB);

    return ;
  },
  args: {
    propertyA: 'Item One',
    propertyB: 'Another Item One',
  },
};
```

```tsx
// YourComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: YourComponent,
  //👇 Creates specific argTypes with options
  argTypes: {
    propertyA: {
      options: ['Item One', 'Item Two', 'Item Three'],
      control: { type: 'select' }, // Automatically inferred when 'options' is defined
    },
    propertyB: {
      options: ['Another Item One', 'Another Item Two', 'Another Item Three'],
    },
  },
});

const someFunction = (valuePropertyA, valuePropertyB) => {
  // Do some logic here
};

export const ExampleStory = meta.story({
  render: (args) => {
    const { propertyA, propertyB } = args;
    //👇 Assigns the function result to a variable
    const someFunctionResult = someFunction(propertyA, propertyB);

    return ;
  },
  args: {
    propertyA: 'Item One',
    propertyB: 'Another Item One',
  },
});
```

Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a `mapping`; additionally, you can specify `control.labels` to configure custom labels for your checkbox, radio, or select input.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const arrows = { ArrowUp, ArrowDown, ArrowLeft, ArrowRight };

const meta = {
  component: Button,
  argTypes: {
    arrow: {
      options: Object.keys(arrows), // An array of serializable values
      mapping: arrows, // Maps serializable option values to complex arg values
      control: {
        type: 'select', // Type 'select' is automatically inferred when 'options' is defined
        labels: {
          // 'labels' maps option values to string labels
          ArrowUp: 'Up',
          ArrowDown: 'Down',
          ArrowLeft: 'Left',
          ArrowRight: 'Right',
        },
      },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const arrows = { ArrowUp, ArrowDown, ArrowLeft, ArrowRight };

const meta = preview.meta({
  component: Button,
  argTypes: {
    arrow: {
      options: Object.keys(arrows), // An array of serializable values
      mapping: arrows, // Maps serializable option values to complex arg values
      control: {
        type: 'select', // Type 'select' is automatically inferred when 'options' is defined
        labels: {
          // 'labels' maps option values to string labels
          ArrowUp: 'Up',
          ArrowDown: 'Down',
          ArrowLeft: 'Left',
          ArrowRight: 'Right',
        },
      },
    },
  },
});
```

Note that both `mapping` and `control.labels` don't have to be exhaustive. If the currently selected option is not listed, it's used verbatim.

## Creating and editing stories from controls

You can create or edit stories, directly from the Controls panel.

### Create a new story

Open the Controls panel for a story and adjust the value of a control. Then save those changes as a new story.

If you're working on a component that does not yet have any stories, you can click the ➕ button in the sidebar to search for your component and have a basic story created for you.

### Edit a story

You can also update a control's value, then save the changes to the story. The story file's code will be updated for you.

### Disable creating and editing of stories

If you don't want to allow the creation or editing of stories from the Controls panel, you can disable this feature by setting the `disableSaveFromUI` parameter to `true` in the `parameters.controls` parameter in your `.storybook/preview.ts|tsx` file.

## Configuration

Controls can be configured in two ways:

- Individual controls can be configured via control annotations.
- The panel's appearance can be configured via parameters.

### Annotation

As shown above, you can configure individual controls with the “control" annotation in the [argTypes](https://storybook.js.org/docs/api/arg-types.md) field of either a component or story. Below is a condensed example and table featuring all available controls.

| Data Type   | Control        | Description                                                                                                                                                                                                                 |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **boolean** | `boolean`      | Provides a toggle for switching between possible states.<br /> `argTypes: { active: { control: 'boolean' }}`                                                                                                                |
| **number**  | `number`       | Provides a numeric input to include the range of all possible values.<br /> `argTypes: { even: { control: { type: 'number', min:1, max:30, step: 2 } }}`                                                                    |
|             | `range`        | Provides a range slider component to include all possible values.<br /> `argTypes: { odd: { control: { type: 'range', min: 1, max: 30, step: 3 } }}`                                                                        |
| **object**  | `object`       | Provides a JSON-based editor component to handle the object's values.<br /> Also allows edition in raw mode.<br /> `argTypes: { user: { control: 'object' }}`                                                               |
| **array**   | `object`       | Provides a JSON-based editor component to handle the array's values.<br /> Also allows edition in raw mode.<br /> `argTypes: { odd: { control: 'object' }}`                                                                 |
|             | `file`         | Provides a file input component that returns an array of URLs.<br /> Can be further customized to accept specific file types.<br /> `argTypes: { avatar: { control: { type: 'file', accept: '.png' } }}`                    |
| **enum**    | `radio`        | Provides a set of radio buttons based on the available options.<br /> `argTypes: { contact: { control: 'radio', options: ['email', 'phone', 'mail'] }}`                                                                     |
|             | `inline-radio` | Provides a set of inlined radio buttons based on the available options.<br /> `argTypes: { contact: { control: 'inline-radio', options: ['email', 'phone', 'mail'] }}`                                                      |
|             | `check`        | Provides a set of checkbox components for selecting multiple options.<br /> `argTypes: { contact: { control: 'check', options: ['email', 'phone', 'mail'] }}`                                                               |
|             | `inline-check` | Provides a set of inlined checkbox components for selecting multiple options.<br /> `argTypes: { contact: { control: 'inline-check', options: ['email', 'phone', 'mail'] }}`                                                |
|             | `select`       | Provides a drop-down list component to handle single value selection. `argTypes: { age: { control: 'select', options: [20, 30, 40, 50] }}`                                                                                  |
|             | `multi-select` | Provides a drop-down list that allows multiple selected values. `argTypes: { countries: { control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }}`                                                                 |
| **string**  | `text`         | Provides a freeform text input. <br /> `argTypes: { label: { control: 'text' }}`                                                                                                                                            |
|             | `color`        | Provides a color picker component to handle color values.<br /> Can be additionally configured to include a set of color presets.<br /> `argTypes: { color: { control: { type: 'color', presetColors: ['red', 'green']} }}` |
|             | `date`         | Provides a datepicker component to handle date selection. `argTypes: { startDate: { control: 'date' }}`                                                                                                                     |

The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object.

```ts
// Gizmo.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Gizmo,
  argTypes: {
    canRotate: {
      control: 'boolean',
    },
    width: {
      control: { type: 'number', min: 400, max: 1200, step: 50 },
    },
    height: {
      control: { type: 'range', min: 200, max: 1500, step: 50 },
    },
    rawData: {
      control: 'object',
    },
    coordinates: {
      control: 'object',
    },
    texture: {
      control: {
        type: 'file',
        accept: '.png',
      },
    },
    position: {
      control: 'radio',
      options: ['left', 'right', 'center'],
    },
    rotationAxis: {
      control: 'check',
      options: ['x', 'y', 'z'],
    },
    scaling: {
      control: 'select',
      options: [10, 50, 75, 100, 200],
    },
    label: {
      control: 'text',
    },
    meshColors: {
      control: {
        type: 'color',
        presetColors: ['#ff0000', '#00ff00', '#0000ff'],
      },
    },
    revisionDate: {
      control: 'date',
    },
  },
} satisfies Meta<typeof Gizmo>;

export default meta;
```

```ts
// Gizmo.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Gizmo,
  argTypes: {
    canRotate: {
      control: 'boolean',
    },
    width: {
      control: { type: 'number', min: 400, max: 1200, step: 50 },
    },
    height: {
      control: { type: 'range', min: 200, max: 1500, step: 50 },
    },
    rawData: {
      control: 'object',
    },
    coordinates: {
      control: 'object',
    },
    texture: {
      control: {
        type: 'file',
        accept: '.png',
      },
    },
    position: {
      control: 'radio',
      options: ['left', 'right', 'center'],
    },
    rotationAxis: {
      control: 'check',
      options: ['x', 'y', 'z'],
    },
    scaling: {
      control: 'select',
      options: [10, 50, 75, 100, 200],
    },
    label: {
      control: 'text',
    },
    meshColors: {
      control: {
        type: 'color',
        presetColors: ['#ff0000', '#00ff00', '#0000ff'],
      },
    },
    revisionDate: {
      control: 'date',
    },
  },
});
```

Numeric data types will default to a `number` control unless additional configuration is provided.

### Parameters

Controls supports the following configuration [parameters](https://storybook.js.org/docs/writing-stories/parameters.md), either globally or on a per-story basis:

#### Show full documentation for each property

Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete [`Controls`](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md) doc block in the controls panel. The description and default value rendering can be [customized](#fully-custom-args) like the doc block.

To enable expanded mode globally, add the following to [`.storybook/preview.ts|tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    controls: { expanded: true },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    controls: { expanded: true },
  },
});
```

Here's what the resulting UI looks like:

![Controls table expanded](../_assets/essentials/addon-controls-expanded.png)

#### Specify initial preset color swatches

For `color` controls, you can specify an array of `presetColors`, either on the `control` in `argTypes`, or as a parameter under the `controls` namespace:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    controls: {
      presetColors: [{ color: '#ff4785', title: 'Coral' }, 'rgba(0, 159, 183, 1)', '#fe4a49'],
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    controls: {
      presetColors: [{ color: '#ff4785', title: 'Coral' }, 'rgba(0, 159, 183, 1)', '#fe4a49'],
    },
  },
});
```

Color presets can be defined as an object with `color` and `title` or a simple CSS color string. These will then be available as swatches in the color picker. When you hover over the color swatch, you'll be able to see its title. It will default to the nearest CSS color name if none is specified.

#### Filtering controls

In specific cases, you may be required to display only a limited number of controls in the controls panel or all except a particular set.

To make this possible, you can use optional `include` and `exclude` configuration fields in the `controls` parameter, which you can define as an array of strings or a regular expression.

Consider the following story snippets:

```ts
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const ArrayInclude: Story = {
  parameters: {
    controls: { include: ['foo', 'bar'] },
  },
};

export const RegexInclude: Story = {
  parameters: {
    controls: { include: /^hello*/ },
  },
};

export const ArrayExclude: Story = {
  parameters: {
    controls: { exclude: ['foo', 'bar'] },
  },
};

export const RegexExclude: Story = {
  parameters: {
    controls: { exclude: /^hello*/ },
  },
};
```

```ts
// YourComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: YourComponent,
});

export const ArrayInclude = meta.story({
  parameters: {
    controls: { include: ['foo', 'bar'] },
  },
});

export const RegexInclude = meta.story({
  parameters: {
    controls: { include: /^hello*/ },
  },
});

export const ArrayExclude = meta.story({
  parameters: {
    controls: { exclude: ['foo', 'bar'] },
  },
});

export const RegexExclude = meta.story({
  parameters: {
    controls: { exclude: /^hello*/ },
  },
});
```

#### Sorting controls

By default, controls are unsorted and use whatever order the args data is processed in (`none`). Additionally, you can sort them alphabetically by the arg's name (`alpha`) or with the required args first (`requiredFirst`).

Consider the following snippet to force required args first:

```ts
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: YourComponent,
  parameters: { controls: { sort: 'requiredFirst' } },
} satisfies Meta<typeof YourComponent>;

export default meta;
```

```ts
// YourComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: YourComponent,
  parameters: { controls: { sort: 'requiredFirst' } },
});
```

### Disable controls for specific properties

Aside from the features already documented here, Controls can also be disabled for individual properties.

Suppose you want to turn off Controls for a property called `foo` in a component's story. The following example illustrates how:

```ts
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: YourComponent,
  argTypes: {
    // foo is the property we want to remove from the UI
    foo: {
      table: {
        disable: true,
      },
    },
  },
} satisfies Meta<typeof YourComponent>;

export default meta;
```

```ts
// YourComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: YourComponent,
  argTypes: {
    // foo is the property we want to remove from the UI
    foo: {
      table: {
        disable: true,
      },
    },
  },
});
```

Resulting in the following change in Storybook UI:

The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation without a control. The following example illustrates how:

```ts
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: YourComponent,
  argTypes: {
    // foo is the property we want to remove from the UI
    foo: {
      control: false,
    },
  },
} satisfies Meta<typeof YourComponent>;

export default meta;
```

```ts
// YourComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: YourComponent,
  argTypes: {
    // foo is the property we want to remove from the UI
    foo: {
      control: false,
    },
  },
});
```

As with other Storybook properties, such as [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases.

### Conditional controls

In some cases, it's useful to be able to conditionally exclude a control based on the value of another control. Controls supports basic versions of these use cases with the `if`, which can take a simple query object to determine whether to include the control.

Consider a collection of "advanced" settings only visible when the user toggles an "advanced" toggle.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  argTypes: {
    label: { control: 'text' }, // Always shows the control
    advanced: { control: 'boolean' },
    // Only enabled if advanced is true
    margin: { control: 'number', if: { arg: 'advanced' } },
    padding: { control: 'number', if: { arg: 'advanced' } },
    cornerRadius: { control: 'number', if: { arg: 'advanced' } },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  argTypes: {
    label: { control: 'text' }, // Always shows the control
    advanced: { control: 'boolean' },
    // Only enabled if advanced is true
    margin: { control: 'number', if: { arg: 'advanced' } },
    padding: { control: 'number', if: { arg: 'advanced' } },
    cornerRadius: { control: 'number', if: { arg: 'advanced' } },
  },
});
```

Or consider a constraint where if the user sets one control value, it doesn't make sense for the user to be able to set another value.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  argTypes: {
    // Button can be passed a label or an image, not both
    label: {
      control: 'text',
      if: { arg: 'image', truthy: false },
    },
    image: {
      control: { type: 'select', options: ['foo.jpg', 'bar.jpg'] },
      if: { arg: 'label', truthy: false },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  argTypes: {
    // Button can be passed a label or an image, not both
    label: {
      control: 'text',
      if: { arg: 'image', truthy: false },
    },
    image: {
      control: { type: 'select', options: ['foo.jpg', 'bar.jpg'] },
      if: { arg: 'label', truthy: false },
    },
  },
});
```

The query object must contain either an `arg` or `global` target:

| field  | type   | meaning                       |
| ------ | ------ | ----------------------------- |
| arg    | string | The ID of the arg to test.    |
| global | string | The ID of the global to test. |

It may also contain at most one of the following operators:

| operator | type    | meaning                                              |
| -------- | ------- | ---------------------------------------------------- |
| truthy   | boolean | Is the target value truthy?                          |
| exists   | boolean | Is the target value defined?                         |
| eq       | any     | Is the target value equal to the provided value?     |
| neq      | any     | Is the target value NOT equal to the provided value? |

If no operator is provided, that is equivalent to `{ truthy: true }`.

## Troubleshooting

### Controls are not automatically generated for my component

If you're working with Angular, Ember, or Web Components, automatic argTypes and controls inference will not work out of the box and requires you to provide [additional configuration](#choosing-the-control-type) to allow Storybook to retrieve the necessary metadata and generate the needed argTypes and controls for your stories. However, if you need additional customization, you can always [define them manually](#fully-custom-args).

### The controls are not updating the story within the auto-generated documentation

If you turned off inline rendering for your stories via the [`inline`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md#inline) configuration option, you would run into a situation where the associated controls are not updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release.

## API

### Parameters

This feature contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `controls` namespace:

#### `disable`

Type: `boolean`

Disable this feature's behavior. If you wish to disable this feature for the entire Storybook, you should [do so in your main configuration file](https://storybook.js.org/docs/essentials/index.md#disabling-features).

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could then be re-enabled by setting it to `false` at the meta (component) or story level.

#### `exclude`

Type: `string[] | RegExp`

Specifies which properties to exclude from the Controls panel. Any properties whose names match the regex or are part of the array will be left out. See [usage example](#filtering-controls), above.

#### `expanded`

Type: `boolean`

Show the full documentation for each property in the Controls panel, including the description and default value. See [usage example](#show-full-documentation-for-each-property), above.

#### `include`

Type: `string[] | RegExp`

Specifies which properties to include in the Controls panel. Any properties whose names don't match the regex or are not part of the array will be left out. See [usage example](#filtering-controls), above.

#### `presetColors`

Type: `(string | { color: string; title?: string })[]`

Specify preset color swatches for the color picker control. The color value may be any valid CSS color. See [usage example](#specify-initial-preset-color-swatches), above.

#### `sort`

Type: `'none' | 'alpha' | 'requiredFirst'`

Default: `'none'`

Specifies how the controls are sorted.

- **none**: Unsorted, displayed in the same order the arg types are processed in
- **alpha**: Sorted alphabetically, by the arg type's name
- **requiredFirst**: Same as `alpha`, with any required arg types displayed first

#### `disableSaveFromUI`

Type: `boolean`

Default: `false`

Disable the ability to create or edit stories from the Controls panel.
> Source: https://storybook.js.org/docs/essentials/controls
---

# Highlight

Storybook's Highlight feature is a helpful tool for visually debugging your components. It allows you to highlight specific DOM nodes within your story when used directly or enhancing addons such as the [Accessibility addon](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) to inform you of accessibility issues within your components.

![Story with highlighted elements](../_assets/essentials/highlight.png)

## Highlighting DOM Elements

To highlight DOM elements with the feature, you'll need to emit the `HIGHLIGHT` event from within a story or an addon. The event payload must contain a `selectors` property assigned to an array of selectors matching the elements you want to highlight. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const Highlighted: Story = {
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        selectors: ['h2', 'a', '.storybook-button'],
      });
      return storyFn();
    },
  ],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const Highlighted = meta.story({
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        selectors: ['h2', 'a', '.storybook-button'],
      });
      return storyFn();
    },
  ],
});
```

We recommend choosing the most specific selector possible to avoid highlighting elements other addons use. This is because the feature tries to match selectors against the entire DOM tree.

### Customize style

By default, highlighted elements contain a standard outline style applied to the selected elements. However, you can enable your custom style by extending the payload object with additional properties to customize the appearance of the highlighted elements. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const StyledHighlight: Story = {
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        selectors: ['h2', 'a', '.storybook-button'],
        styles: {
          backgroundColor: `color-mix(in srgb, hotpink, transparent 90%)`,
          outline: '3px solid hotpink',
          animation: 'pulse 3s linear infinite',
          transition: 'outline-offset 0.2s ease-in-out',
        },
        hoverStyles: {
          outlineOffset: '3px',
        },
        focusStyles: {
          backgroundColor: 'transparent',
        },
        keyframes: `@keyframes pulse {
          0% { outline-color: rgba(255, 105, 180, 1); }
          50% { outline-color: rgba(255, 105, 180, 0.2); }
          100% { outline-color: rgba(255, 105, 180, 1); }
        }`,
      });
      return storyFn();
    },
  ],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const StyledHighlight = meta.story({
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        selectors: ['h2', 'a', '.storybook-button'],
        styles: {
          backgroundColor: `color-mix(in srgb, hotpink, transparent 90%)`,
          outline: '3px solid hotpink',
          animation: 'pulse 3s linear infinite',
          transition: 'outline-offset 0.2s ease-in-out',
        },
        hoverStyles: {
          outlineOffset: '3px',
        },
        focusStyles: {
          backgroundColor: 'transparent',
        },
        keyframes: `@keyframes pulse {
          0% { outline-color: rgba(255, 105, 180, 1); }
          50% { outline-color: rgba(255, 105, 180, 0.2); }
          100% { outline-color: rgba(255, 105, 180, 1); }
        }`,
      });
      return storyFn();
    },
  ],
});
```

These properties are optional, and you can use them to customize the appearance of the highlighted elements. The `hoverStyles` and `focusStyles` properties are recommended for use with the `menu` property. Pseudo-classes and pseudo-elements are not supported.

### Highlight menu

The Highlight feature includes a built-in debugging option, allowing you to select the highlighted elements when you click them. This is particularly useful for inspecting the elements affected by the feature, as it lets you preview a list of elements matching the selector you provided. To enable it, add a `menu` property in the payload object containing additional information about the elements or trigger actions. Each item must include an `id` and a `title`, and you can also provide an optional `selectors` property to limit the menu item to specific highlighted elements.

![Menu with custom items](../_assets/essentials/highlight-menu.png)

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const StyledHighlight: Story = {
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        selectors: ['h2', 'a', '.storybook-button'],
        menu: [
          [
            {
              id: 'button-name',
              title: 'Login',
              description: 'Navigate to the login page',
              clickEvent: 'my-menu-click-event',
            },
            {
              id: 'h2-home',
              title: 'Acme',
              description: 'Navigate to the home page',
            },
          ],
        ],
      });
      return storyFn();
    },
  ],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const StyledHighlight = meta.story({
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        selectors: ['h2', 'a', '.storybook-button'],
        menu: [
          [
            {
              id: 'button-name',
              title: 'Login',
              description: 'Navigate to the login page',
              clickEvent: 'my-menu-click-event',
            },
            {
              id: 'h2-home',
              title: 'Acme',
              description: 'Navigate to the home page',
            },
          ],
        ],
      });
      return storyFn();
    },
  ],
});
```

When enabled, the menu will be displayed when you click on the selected element matching your provided selectors. However, if you don't want to show any information, you can omit the items or set the `menu` property to an empty array to show the default menu.

![Menu of selectable targets](../_assets/essentials/highlight-selectable.png)

## Remove highlights

If you need to remove a highlight from a specific element, you can do so by emitting the `REMOVE_HIGHLIGHT` event and providing the `id` of the highlight you want to remove. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const RemoveHighlight: Story = {
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        id: 'my-unique-id',
        selectors: ['header', 'section', 'footer'],
      });
      emit(REMOVE_HIGHLIGHT, 'my-unique-id');
      return storyFn();
    },
  ],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const RemoveHighlight = meta.story({
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(HIGHLIGHT, {
        id: 'my-unique-id',
        selectors: ['header', 'section', 'footer'],
      });
      emit(REMOVE_HIGHLIGHT, 'my-unique-id');
      return storyFn();
    },
  ],
});
```

The `emit` function derived from the `useChannel` API hook creates a communication channel in Storybook's UI to listen for events and update the UI accordingly. The Highlight feature uses this channel to listen to custom events and update the highlighted elements (if any) accordingly.

## Reset highlighted elements

Out of the box, Storybook automatically removes highlighted elements when transitioning between stories. However, if you need to clear them manually, you can emit the `RESET_HIGHLIGHT` event from within a story or an addon. This removes all highlights, even ones created by other addons. For example:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const ResetHighlight: Story = {
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(RESET_HIGHLIGHT); //👈 Remove previously highlighted elements
      emit(HIGHLIGHT, {
        selectors: ['header', 'section', 'footer'],
      });
      return storyFn();
    },
  ],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const ResetHighlight = meta.story({
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(RESET_HIGHLIGHT); //👈 Remove previously highlighted elements
      emit(HIGHLIGHT, {
        selectors: ['header', 'section', 'footer'],
      });
      return storyFn();
    },
  ],
});
```

## Scroll element into view

The Highlight feature allows you to scroll an element into view and highlight it. To enable it, emit the `SCROLL_INTO_VIEW` event from within a story or an addon. The event payload must contain a `selector` property to target the element you want to scroll into view. When the element is visible, it will be highlighted for a brief moment.

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const ScrollIntoView: Story = {
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(SCROLL_INTO_VIEW, '#footer');
      return storyFn();
    },
  ],
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const ScrollIntoView = meta.story({
  decorators: [
    (storyFn) => {
      const emit = useChannel({});
      emit(SCROLL_INTO_VIEW, '#footer');
      return storyFn();
    },
  ],
});
```

## API

### Parameters

This feature contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `highlight` namespace:

#### `disable`

Type: `boolean`

Disable this feature's behavior. If you wish to turn off this feature for the entire Storybook, you should [do so in your main configuration file](https://storybook.js.org/docs/essentials/index.md#disabling-features).

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.

### Exports

This feature contributes the following exports to Storybook:

```js

  HIGHLIGHT,
  REMOVE_HIGHLIGHT,
  RESET_HIGHLIGHT,
  SCROLL_INTO_VIEW,
} from 'storybook/highlight';
```

#### `HIGHLIGHT`

An event to highlight DOM elements. The event payload must contain a `selectors` property assigned to an array of selectors matching the elements you want to highlight. It can be extended with an optional object containing additional configuration options. See the [usage example](#highlighting-dom-elements) above.

```ts

channel.emit(
  HIGHLIGHT,
  options, // The available configuration options inheriting from the HighlightOptions API
);
```

The `options` object contains the following properties:

```ts
interface HighlightOptions {
  /** Unique identifier for the highlight, required if you want to remove the highlight later */
  id?: string;
  /** HTML selectors of the elements */
  selectors: string[];
  /** Priority of the highlight, higher takes precedence, defaults to 0 */
  priority?: number;
  /** CSS styles to apply to the highlight */
  styles?: Record<string, string>;
  /** CSS styles to apply to the highlight when it is hovered */
  hoverStyles?: Record<string, string>;
  /** CSS styles to apply to the highlight when it is focused or selected */
  focusStyles?: Record<string, string>;
  /** Keyframes required for animations */
  keyframes?: string;
  /** Groups of menu items to show when the highlight is selected */
  menu?: HighlightMenuItem[][];
}

interface HighlightMenuItem {
  /** Unique identifier for the menu item */
  id: string;
  /** Title of the menu item */
  title: string;
  /** Description of the menu item */
  description?: string;
  /** Icon for the menu item, left side */
  iconLeft?: 'chevronLeft' | 'chevronRight' | 'info' | 'shareAlt';
  /** Icon for the menu item, right side */
  iconRight?: 'chevronLeft' | 'chevronRight' | 'info' | 'shareAlt';
  /** Name for a channel event to trigger when the menu item is clicked */
  clickEvent?: string;
  /** HTML selectors for which this menu item should show (subset of HighlightOptions['selectors']) */
  selectors?: HighlightOptions['selectors'];
}
```

Menu items can specify a `clickEvent` to be emitted on the channel when the item is clicked. The channel event will receive two arguments: the menu item `id` and a `ClickEventDetails` object with the following properties:

```ts
interface ClickEventDetails {
  // Position and dimensions of the element on the page
  top: number;
  left: number;
  width: number;
  height: number;
  // Selector(s) which matched the element
  selectors: string[];
  // DOM element details
  element: {
    attributes: Record<string, string>;
    localName: string;
    tagName: string;
    outerHTML: string;
  };
}
```

To listen for this event (assuming `clickEvent: 'MY_CLICK_EVENT'`):

```ts

const handleClickEvent = (itemId: string, details: ClickEventDetails) => {
  // Handle the menu item click event
};

// When you have a channel instance:
channel.on('MY_CLICK_EVENT', handleClickEvent);

// Or from a decorator:
useChannel(
  {
    MY_CLICK_EVENT: handleClickEvent,
  },
  [handleClickEvent],
);
```

#### `REMOVE_HIGHLIGHT`

An event that removes a previously created highlight. The event payload must contain an `id` property assigned to the id of the highlight you want to remove. See the [usage example](#remove-highlights) above.

```ts

channel.emit(
  REMOVE_HIGHLIGHT,
  id, // The id of the previously created highlight to be removed
);
```

#### `RESET_HIGHLIGHT`

An event to clear all highlights from highlighted elements. See the [usage example](#reset-highlighted-elements) above.

```ts

channel.emit(RESET_HIGHLIGHT);
```

#### `SCROLL_INTO_VIEW`

An event to scroll a DOM element into view and briefly highlight it. The event payload must contain a selector property assigned to the selector of the element you want to scroll into view. Optionally, you can provide a [`options`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#scrollintoviewoptions) object to customize the scroll behavior. See the [usage example](#scroll-element-into-view) above.

```ts

channel.emit(
  SCROLL_INTO_VIEW,
  selector // Element selector to scroll into view
  options // An object inheriting from ScrollIntoViewOptions API to customize the scroll behavior
);
```
> Source: https://storybook.js.org/docs/essentials/highlight
---

# Measure & outline

Storybook's measure and outline features give you the necessary tooling to inspect and visually debug CSS layout and alignment issues within your stories. It makes it easy to catch UI bugs early in development.

## Measure

While working with composite components or page layouts, dealing with whitespace (i.e., `margin`, `padding`, `border`) and individual component measurements can be tedious. It would require that you open up the browser's development tools and manually inspect the DOM tree for issues and UI bugs.

Instead, you can quickly visualize each component's measurements by clicking the measure button in the toolbar. Now when you hover over an element in your story, that element's dimensions and any whitespace (i.e., `margin`, `padding`, `border`) will be shown.

![Measure feature enabled displaying the component's dimensions](../_assets/essentials/addon-measure.png)

Alternatively you can press the `m` key on your keyboard to toggle measure on and off.

## Outline

When building your layouts, checking the visual alignment of all components can be pretty complicated, especially if your components are spread apart or contain unique shapes.

Click the outline button in the toolbar to toggle the outlines associated with all your UI elements, allowing you to spot bugs and broken layouts instantly.

![Outline feature enabled on the component's story](../_assets/essentials/addon-outline.png)

## API

### Parameters

These features contribute the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `measure` or `outline` namespace:

#### `disable`

Type: `boolean`

Disable the feature's behavior. If you wish to disable the feature for the entire Storybook, you should [do so in your main configuration file](https://storybook.js.org/docs/essentials/index.md#disabling-features).

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could then be re-enabled by setting it to `false` at the meta (component) or story level.
> Source: https://storybook.js.org/docs/essentials/measure-and-outline
---

# Toolbars & globals

Storybook ships with features to control the [viewport](https://storybook.js.org/docs/essentials/viewport.md) and [background](https://storybook.js.org/docs/essentials/backgrounds.md) the story renders in. Similarly, you can use built-in features to create toolbar items which control special “globals”. You can then read the global values to create [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) to control story rendering.

![Toolbars and globals](../_assets/essentials/toolbars-and-globals.png)

## Globals

Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`). Instead, they are typically used in decorators, which apply to all stories.

When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them.

## Global types and the toolbar annotation

Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  globalTypes: {
    theme: {
      description: 'Global theme for components',
      toolbar: {
        // The label to show for this toolbar item
        title: 'Theme',
        icon: 'circlehollow',
        // Array of plain string values or MenuItem shape (see below)
        items: ['light', 'dark'],
        // Change title based on selected value (recommended for consistency with the Storybook UI)
        dynamicTitle: true,
      },
    },
  },
  initialGlobals: {
    theme: 'light',
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  globalTypes: {
    theme: {
      description: 'Global theme for components',
      toolbar: {
        // The label to show for this toolbar item
        title: 'Theme',
        icon: 'circlehollow',
        // Array of plain string values or MenuItem shape (see below)
        items: ['light', 'dark'],
        // Change title based on selected value (recommended for consistency with the Storybook UI)
        dynamicTitle: true,
      },
    },
  },
  initialGlobals: {
    theme: 'light',
  },
});
```

As globals are _global_ you can _only_ set `globalTypes` and `initialGlobals` in [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering).

When you start your Storybook, your toolbar should have a new dropdown menu with the `light` and `dark` options.

## Create a decorator

We have a `global` implemented. Let's wire it up! We can consume our new `theme` global in a decorator using the `context.globals.theme` value.

For example, suppose you are using [`styled-components`](https://styled-components.com/). You can add a theme provider decorator to your [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) config:

```tsx
// .storybook/preview.tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const preview: Preview = {
  decorators: [
    (Story, context) => {
      const theme = MyThemes[context.globals.theme];
      return (
        
          
        
      );
    },
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [
    (Story, context) => {
      const theme = MyThemes[context.globals.theme];
      return (
        
          
        
      );
    },
  ],
});
```

Depending on your framework and theming library, you can extend your [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) and provide a decorator to load the theme. For example:

```tsx
// .storybook/preview.tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const preview: Preview = {
  decorators: [
    (Story, context) => {
      const theme = MyThemes[context.globals.theme];
      return (
        
          
        
      );
    },
  ],
};

export default preview;
```

```tsx
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [
    (Story, context) => {
      const theme = MyThemes[context.globals.theme];
      return (
        
          
        
      );
    },
  ],
});
```

## Setting globals on a story

When a global value is changed with a toolbar menu in Storybook, that value continues to be used as you navigate between stories. But sometimes a story requires a specific value to render correctly, e.g., when testing against a particular environment.

To ensure that a story always uses a specific global value, regardless of what has been chosen in the toolbar, you can set the `globals` annotation on a story or component. This overrides the global value for those stories and disables the toolbar menu for that global when viewing the stories.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework (e.g., react-vite, vue3-vite, etc.)

const meta = {
  component: Button,
  globals: {
    // 👇 Set background value for all component stories
    backgrounds: { value: 'gray', grid: false },
  },
} satisfies Meta<typeof Button>;

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

export const OnDark: Story = {
  globals: {
    // 👇 Override background value for this story
    backgrounds: { value: 'dark' },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  globals: {
    // 👇 Set background value for all component stories
    backgrounds: { value: 'gray', grid: false },
  },
});

export const OnDark = meta.story({
  globals: {
    // 👇 Override background value for this story
    backgrounds: { value: 'dark' },
  },
});
```

In the example above, Storybook will force all Button stories to use a gray background color, except the `OnDark` story, which will use the dark background. For all Button stories, the toolbar menu will be disabled for the `backgrounds` global, with a tooltip explaining that the global is set at the story level.

Configuring a story's `globals` annotation to override the project-level global settings is useful but should be used with moderation. Globals that are _not_ defined at the story level can be selected interactively in Storybook's UI, allowing users to explore every existing combination of values (e.g., global values, [`args`](https://storybook.js.org/docs/writing-stories/args.md)). Setting them at the story level will disable that control, preventing users from exploring the available options.

## Advanced usage

So far, we've created and used a global inside Storybook.

Now, let's take a look at a more complex example. Suppose we wanted to implement a new global called **locale** for internationalization, which shows a flag on the right side of the toolbar.

In your [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering), add the following:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  globalTypes: {
    locale: {
      description: 'Internationalization locale',
      toolbar: {
        icon: 'globe',
        items: [
          { value: 'en', right: '🇺🇸', title: 'English' },
          { value: 'fr', right: '🇫🇷', title: 'Français' },
          { value: 'es', right: '🇪🇸', title: 'Español' },
          { value: 'zh', right: '🇨🇳', title: '中文' },
          { value: 'kr', right: '🇰🇷', title: '한국어' },
        ],
      },
    },
  },
  initialGlobals: {
    locale: 'en',
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  globalTypes: {
    locale: {
      description: 'Internationalization locale',
      toolbar: {
        icon: 'globe',
        items: [
          { value: 'en', right: '🇺🇸', title: 'English' },
          { value: 'fr', right: '🇫🇷', title: 'Français' },
          { value: 'es', right: '🇪🇸', title: 'Español' },
          { value: 'zh', right: '🇨🇳', title: '中文' },
          { value: 'kr', right: '🇰🇷', title: '한국어' },
        ],
      },
    },
  },
  initialGlobals: {
    locale: 'en',
  },
});
```

The `icon` element used in the examples loads the icons from the `@storybook/icons` package. See [here](https://storybook.js.org/docs/faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use.

Adding the configuration element `right` will display the text on the right side in the toolbar menu once you connect it to a decorator.

Here's a list of the available configuration options.

| MenuItem  | Type   | Description                                                     | Required |
| --------- | ------ | --------------------------------------------------------------- | -------- |
| **value** | String | The string value of the menu that gets set in the globals       | Yes      |
| **title** | String | The main text of the title                                      | Yes      |
| **right** | String | A string that gets displayed on the right side of the menu      | No       |
| **icon**  | String | An icon that gets shown in the toolbar if this item is selected | No       |

## Consuming globals from within a story

We recommend consuming globals from within a decorator and defining a global setting for all stories.

But we're aware that sometimes it's more beneficial to use toolbar options on a per-story basis.

Using the example above, you can modify any story to retrieve the **Locale** `global` from the story context:

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

const getCaptionForLocale = (locale) => {
  switch (locale) {
    case 'es':
      return 'Hola!';
    case 'fr':
      return 'Bonjour!';
    case 'kr':
      return '안녕하세요!';
    case 'zh':
      return '你好!';
    default:
      return 'Hello!';
  }
};

export const StoryWithLocale = {
  render: (args, { globals: { locale } }) => {
    const caption = getCaptionForLocale(locale);
    return <p>{caption}</p>;
  },
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

const getCaptionForLocale = (locale) => {
  switch (locale) {
    case 'es':
      return 'Hola!';
    case 'fr':
      return 'Bonjour!';
    case 'kr':
      return '안녕하세요!';
    case 'zh':
      return '你好!';
    default:
      return 'Hello!';
  }
};

export const StoryWithLocale = meta.story({
  render: (args, { globals: { locale } }) => {
    const caption = getCaptionForLocale(locale);
    return <p>{caption}</p>;
  },
});
```

## Consuming globals from within an addon

If you're working on a Storybook addon and need to retrieve globals, you can do so. The `storybook/manager-api` module provides a hook for this scenario. You can use the [`useGlobals()`](https://storybook.js.org/docs/addons/addons-api.md#useglobals) hook to retrieve any globals you want.

Using the ThemeProvider example above, you could expand it to display which theme is active inside a panel as such:

```js
// your-addon-register-file.js

  AddonPanel,
  Placeholder,
  Separator,
  Source,
  Spaced,
  Title,
} from 'storybook/internal/components';

// Function to obtain the intended theme
const getTheme = (themeName) => {
  return MyThemes[themeName];
};

const ThemePanel = (props) => {
  const [{ theme: themeName }] = useGlobals();

  const selectedTheme = getTheme(themeName);

  return (
    
      {selectedTheme ? (
        
          {selectedTheme.name}
          <p>The full theme object</p>
          
        
      ) : (
        No theme selected
      )}
    
  );
};
```

## Updating globals from within an addon

If you're working on a Storybook addon that needs to update the global and refresh the UI, you can do so. As mentioned previously, the `storybook/manager-api` module provides the necessary hook for this scenario. You can use the `updateGlobals` function to update any global values you need.

For example, if you were working on a [toolbar addon](https://storybook.js.org/docs/addons/addon-types.md#toolbars), and you want to refresh the UI and update the global once the user clicks on a button:

```js
// your-addon-register-file.js

const ExampleToolbar = () => {
  const [globals, updateGlobals] = useGlobals();

  const isActive = globals['my-param-key'] || false;

  // Function that will update the global value and trigger a UI refresh.
  const refreshAndUpdateGlobal = () => {
    // Updates Storybook global value
    updateGlobals({
      ['my-param-key']: !isActive,
    });
    // Invokes Storybook's addon API method (with the FORCE_RE_RENDER) event to trigger a UI refresh
    addons.getChannel().emit(FORCE_RE_RENDER);
  };

  const toggleOutline = useCallback(() => refreshAndUpdateGlobal(), [isActive]);

  return (
    
      
    
  );
};
```
> Source: https://storybook.js.org/docs/essentials/toolbars-and-globals
---

# Viewport

The viewport feature allows you to adjust the dimensions of the iframe your story is rendered in. It makes it easy to develop responsive UIs.

![Storybook with default viewports visible](../_assets/essentials/addon-viewports.png)

## Configuration

Out of the box, the viewport feature offers you a standard set of viewports that you can use. If you want to change the default set of viewports, you can configure your own viewports with the `viewport` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in your [`.storybook/preview.*`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering).

You can define the available viewports using the [`options` property](#options) and set the initial viewport using the `initialGlobals` property:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
});
```

### Use a detailed set of devices

By default, the viewport feature will use a minimal set of viewports, which enables you to test your UI in common responsive scenarios. These are also available in the [`MINIMAL_VIEWPORTS` export](#minimal_viewports) and include the following devices:

| Key       | Description  | Dimensions<br />(<abbr title="width">w</abbr>×<abbr title="height">h</abbr>, px) |
| --------- | ------------ | -------------------------------------------------------------------------------- |
| `mobile1` | Small mobile | 320 × 568                                                                        |
| `mobile2` | Large mobile | 414 × 896                                                                        |
| `tablet`  | Tablet       | 834 × 1112                                                                       |
| `desktop` | Desktop      | 1024 × 1280                                                                      |

If you need a more detailed set of devices, you can use the [`INITIAL_VIEWPORTS` export](#initial_viewports), which includes the following devices:

| Key              | Description                | Dimensions<br />(<abbr title="width">w</abbr>×<abbr title="height">h</abbr>, px) |
| ---------------- | -------------------------- | -------------------------------------------------------------------------------- |
| `iphone5`        | iPhone 5                   | 320 × 568                                                                        |
| `iphone6`        | iPhone 6                   | 375 × 667                                                                        |
| `iphone6p`       | iPhone 6 Plus              | 414 × 736                                                                        |
| `iphone8p`       | iPhone 8 Plus              | 414 × 736                                                                        |
| `iphonex`        | iPhone X                   | 375 × 812                                                                        |
| `iphonexr`       | iPhone XR                  | 414 × 896                                                                        |
| `iphonexsmax`    | iPhone XS Max              | 414 × 896                                                                        |
| `iphonese2`      | iPhone SE (2nd generation) | 375 × 667                                                                        |
| `iphone12mini`   | iPhone 12 mini             | 375 × 812                                                                        |
| `iphone12`       | iPhone 12                  | 390 × 844                                                                        |
| `iphone12promax` | iPhone 12 Pro Max          | 428 × 926                                                                        |
| `iphoneSE3`      | iPhone SE 3rd generation   | 375 × 667                                                                        |
| `iphone13`       | iPhone 13                  | 390 × 844                                                                        |
| `iphone13pro`    | iPhone 13 Pro              | 390 × 844                                                                        |
| `iphone13promax` | iPhone 13 Pro Max          | 428 × 926                                                                        |
| `iphone14`       | iPhone 14                  | 390 × 844                                                                        |
| `iphone14pro`    | iPhone 14 Pro              | 393 × 852                                                                        |
| `iphone14promax` | iPhone 14 Pro Max          | 430 × 932                                                                        |
| `galaxys5`       | Galaxy S5                  | 360 × 640                                                                        |
| `galaxys9`       | Galaxy S9                  | 360 × 740                                                                        |
| `nexus5x`        | Nexus 5X                   | 412 × 668                                                                        |
| `nexus6p`        | Nexus 6P                   | 412 × 732                                                                        |
| `pixel`          | Pixel                      | 540 × 960                                                                        |
| `pixelxl`        | Pixel XL                   | 720 × 1280                                                                       |
| `ipad`           | iPad                       | 768 × 1024                                                                       |
| `ipad10p`        | iPad Pro 10.5-in           | 834 × 1112                                                                       |
| `ipad11p`        | iPad Pro 11-in             | 834 × 1194                                                                       |
| `ipad12p`        | iPad Pro 12.9-in           | 1024 × 1366                                                                      |

To use the detailed set of devices, you can adjust the `options` property in your configuration to include the `INITIAL_VIEWPORTS` export:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
});
```

### Add new devices

If the predefined viewports don't meet your needs, you can add new devices to the list of viewports. For example, let's add two Kindle devices to the default set of minimal viewports:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const kindleViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};

const preview: Preview = {
  parameters: {
    viewport: {
      options: {
        ...MINIMAL_VIEWPORTS,
        ...kindleViewports,
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const kindleViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};

export default definePreview({
  parameters: {
    viewport: {
      options: {
        ...MINIMAL_VIEWPORTS,
        ...kindleViewports,
      },
    },
  },
});
```

### Configuring per component or story

In some cases, it's not practical for you to use a specific visual viewport on a global scale, and you need to adjust it to an individual story or set of stories for a component.

[Parameters](https://storybook.js.org/docs/writing-stories/parameters.md) can be applied at the project, component, and story levels, which allows you to specify the configuration where needed. For example, you can set the available viewports for all of the stories for a component like so:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  component: MyComponent,
  parameters: {
    viewport: {
      //👇 Set available viewports for every story in the file
      options: INITIAL_VIEWPORTS,
    },
  },
} satisfies Meta<typeof MyComponent>;

export default meta;
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
  parameters: {
    viewport: {
      //👇 Set available viewports for every story in the file
      options: INITIAL_VIEWPORTS,
    },
  },
});
```

## Defining the viewport for a story

The Viewport module enables you to change the viewport applied to a story by selecting from the list of predefined viewports in the toolbar. If needed, you can set a story to default to a specific viewport by using the `globals` option:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  globals: {
    // 👇 Set viewport for all component stories
    viewport: { value: 'tablet', isRotated: false },
  },
} satisfies Meta<typeof Button>;

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

export const OnPhone: Story = {
  globals: {
    // 👇 Override viewport for this story
    viewport: { value: 'mobile1', isRotated: false },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  globals: {
    // 👇 Set viewport for all component stories
    viewport: { value: 'tablet', isRotated: false },
  },
});

export const OnPhone = meta.story({
  globals: {
    // 👇 Override viewport for this story
    viewport: { value: 'mobile1', isRotated: false },
  },
});
```

When you specify a viewport for a story (or a component's stories) using `globals`, the viewport is applied and cannot be changed using the toolbar. This is useful to ensure a story is always rendered on a specific viewport.

## API

### Keyboard shortcuts

If you need, you can edit these on the shortcuts page.

- Next viewport: <kbd>alt</kbd> + <kbd>v</kbd>
- Previous viewport: <kbd>alt</kbd> + <kbd>shift</kbd> + <kbd>v</kbd>
- Reset viewport: <kbd>alt</kbd> + <kbd>control</kbd> + <kbd>v</kbd>

### Globals

This module contributes the following globals to Storybook, under the `viewport` namespace:

#### `value`

Type: `string`

When set, the viewport is applied and cannot be changed using the toolbar. Must match the key of one of the [available viewports](#options).

#### `isRotated`

Type: `boolean`

When true, the viewport applied will be rotated 90°, e.g., from portrait to landscape orientation.

### Parameters

This module contributes the following [parameters](https://storybook.js.org/docs/writing-stories/parameters.md) to Storybook, under the `viewport` namespace:

#### `disable`

Type: `boolean`

Turn off this module's behavior. This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.

#### `options`

Type:

```ts
{
  [key: string]: {
    name: string;
    styles: { height: string, width: string };
    type: 'desktop' | 'mobile' | 'tablet' | 'other';
  };
}
```

Specify the available viewports. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`.

### Exports

This module contributes the following exports to Storybook:

```js

```

#### `INITIAL_VIEWPORTS`

Type: `object`

The full set of initial viewports provided by the Viewport module [listed above](#use-a-detailed-set-of-devices).

#### `MINIMAL_VIEWPORTS`

Type: `object`

A minimal set of viewports provided by the Viewport module [listed above](#use-a-detailed-set-of-devices). These are used by default.
> Source: https://storybook.js.org/docs/essentials/viewport
---

# Introduction to addons

Addons extend Storybook with features and integrations that are not built into the core. Most Storybook features are implemented as addons. For instance: [documentation](https://storybook.js.org/docs/writing-docs.md), [accessibility testing](https://storybook.js.org/docs/writing-tests/accessibility-testing.md), [interactive controls](https://storybook.js.org/docs/essentials/controls.md), among others.
The [addon API](https://storybook.js.org/docs/addons/addons-api.md) makes it easy for you to configure and customize Storybook in new ways. There are countless addons made by the community that unlocks time-saving workflows.

Browse our [addon catalog](https://storybook.js.org/addons) to install an existing addon or as inspiration for your own addon.

## Storybook basics

Before writing your first [addon](https://storybook.js.org/addons), let’s take a look at the basics of Storybook’s architecture. While Storybook presents a unified user interface, under the hood it’s divided down the middle into **Manager** and **Preview**.

The **Manager** is the UI responsible for rendering the:

- 🔍 Search
- 🧭 Navigation
- 🔗 Toolbars
- 📦 Addons

The **Preview** area is an `iframe` where your stories are rendered.

![Storybook detailed window](../_assets/addons/manager-preview.png)

Because both elements run in their own separate `iframes`, they use a communication channel to keep in sync. For example, when you select a story in the Manager an event is dispatched across the channel notifying the Preview to render the story.

## Anatomy of an addon

Storybook addons allow you to extend what's already possible with Storybook, everything from the [user interface](https://storybook.js.org/docs/addons/addon-types.md) to the [API](https://storybook.js.org/docs/addons/addons-api.md). Each one is classified into two broader categories.

### UI-based addons

[UI-based addons](https://storybook.js.org/docs/addons/addon-types.md#ui-based-addons) focus on customizing Storybook's user interface to extend your development workflow. Examples of UI-based addons include: [Controls](https://storybook.js.org/docs/essentials/controls.md), [Docs](https://storybook.js.org/docs/writing-docs.md) and [Accessibility](https://storybook.js.org/docs/writing-tests/accessibility-testing.md).

[Learn how to write an addon »](https://storybook.js.org/docs/addons/writing-addons.md)

### Preset addons

[Preset addons](https://storybook.js.org/docs/addons/addon-types.md#preset-addons) help you integrate Storybook with other technologies and libraries. An examples of a preset addons is [preset-create-react-app](https://github.com/storybookjs/presets/tree/master/packages/preset-create-react-app).

[Learn how to write a preset addon »](https://storybook.js.org/docs/addons/writing-presets.md)
> Source: https://storybook.js.org/docs/addons
---

# Install addons

Storybook has [hundreds of reusable addons](https://storybook.js.org/integrations) packaged as NPM modules. Let's walk through how to extend Storybook by installing and registering addons.

## Automatic installation

Storybook includes a [`storybook add`](https://storybook.js.org/docs/api/cli-options.md#add) command to automate the setup of addons. Several community-led addons can be added using this command, except for preset addons. We encourage you to read the addon's documentation to learn more about its installation process.

Run the `storybook add` command using your chosen package manager, and the CLI will update your Storybook configuration to include the addon and install any necessary dependencies.

```shell
npx storybook@latest add @storybook/addon-a11y
```

```shell
pnpm dlx storybook@latest add @storybook/addon-a11y
```

```shell
yarn dlx storybook@latest add @storybook/addon-a11y
```

If you're attempting to install multiple addons at once, it will only install the first addon that was specified. This is a known limitation of the current implementation and will be addressed in a future release.

### Manual installation

Storybook addons are always added through the [`addons`](https://storybook.js.org/docs/api/main-config/main-config-addons.md) configuration array in [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure.md). The following example shows how to manually add the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) to Storybook.

Run the following command with your package manager of choice to install the addon.

```shell
npm install @storybook/addon-a11y --save-dev
```

```shell
pnpm add --save-dev @storybook/addon-a11y
```

```shell
yarn add --dev @storybook/addon-a11y
```

Next, update `.storybook/main.js|ts` to the following:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other Storybook addons
    '@storybook/addon-a11y', //👈 The a11y addon goes here
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other Storybook addons
    '@storybook/addon-a11y', //👈 The a11y addon goes here
  ],
});
```

When you run Storybook, the accessibility testing addon will be enabled.

![Storybook addon installed and registered](../_assets/addons/storybook-addon-installed-registered.png)

### Removing addons

To remove an addon from Storybook, you can choose to manually uninstall it and remove it from the configuration file (i.e., [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure.md)) or opt-in to do it automatically via the CLI with the [`remove`](https://storybook.js.org/docs/api/cli-options.md#remove) command. For example, to remove the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) from Storybook with the CLI, run the following command:

```shell
npx storybook@latest remove @storybook/addon-a11y
```

```shell
pnpm dlx storybook@latest remove @storybook/addon-a11y
```

```shell
yarn dlx storybook@latest remove @storybook/addon-a11y
```
> Source: https://storybook.js.org/docs/addons/install-addons
---

# Write an addon

Storybook addons are a powerful way to extend Storybook's functionality and customize the development experience. They can be used to add new features, customize the UI, or integrate with third-party tools.

## What are we going to build?

This reference guide is to help you develop a mental model for how Storybook addons work by building a simple addon based on the popular [Outline addon](https://storybook.js.org/addons/@storybook/addon-outline/) (which is the historical basis for the built-in [outline feature](https://storybook.js.org/docs/essentials/measure-and-outline.md#outline)). Throughout this guide, you'll learn how addons are structured, Storybook's APIs, how to test your addon locally, and how to publish it.

![Fully implemented Storybook addon](../_assets/addons/storybook-addon-finished-state.png)

## Addon anatomy

There are two main categories of addons, each with its role:

- **UI-based**: These addons are responsible for customizing the interface, enabling shortcuts for common tasks, or displaying additional information in the UI.
- **Presets**: [These](https://storybook.js.org/docs/addons/writing-presets.md) are pre-configured settings or configurations that enable developers to quickly set up and customize their environment with a specific set of features, functionality, or technology.

### UI-based addons

The addon built in this guide is a UI-based addon, specifically a [toolbar](https://storybook.js.org/docs/addons/addon-types.md#toolbars) addon, enabling users to draw outlines around each element in the story through a shortcut or click of a button. UI addons can create other types of UI elements, each with its function: [panels](https://storybook.js.org/docs/addons/addon-types.md#panels) and [tabs](https://storybook.js.org/docs/addons/addon-types.md#tabs), providing users with various ways to interact with the UI.

```tsx
// src/Tool.tsx — Toolbar

export const Tool = memo(function MyAddonSelector() {
  const [globals, updateGlobals] = useGlobals();
  const api = useStorybookApi();

  const isActive = [true, 'true'].includes(globals[PARAM_KEY]);

  const toggleMyTool = useCallback(() => {
    updateGlobals({
      [PARAM_KEY]: !isActive,
    });
  }, [isActive]);

  useEffect(() => {
    api.setAddonShortcut(ADDON_ID, {
      label: 'Toggle Outline',
      defaultShortcut: ['alt', 'O'],
      actionName: 'outline',
      showInMenu: false,
      action: toggleMyTool,
    });
  }, [toggleMyTool, api]);

  return (
    
      
    
  );
});
```

```tsx
// src/Panel.tsx — Panel

// See https://github.com/storybookjs/addon-kit/blob/main/src/components/PanelContent.tsx for an example of a PanelContent component

interface PanelProps {
  active: boolean;
}

export const Panel: React.FC<PanelProps> = (props) => {
  // https://storybook.js.org/docs/addons/addons-api#useaddonstate
  const [results, setState] = useAddonState(ADDON_ID, {
    danger: [],
    warning: [],
  });

  // https://storybook.js.org/docs/addons/addons-api#usechannel
  const emit = useChannel({
    [EVENTS.RESULT]: (newResults) => setState(newResults),
  });

  return (
    
      <PanelContent
        results={results}
        fetchData={() => {
          emit(EVENTS.REQUEST);
        }}
        clearData={() => {
          emit(EVENTS.CLEAR);
        }}
      />
    
  );
};
```

```tsx
// src/Tab.tsx — Tab

// See https://github.com/storybookjs/addon-kit/blob/main/src/components/TabContent.tsx for an example of a TabContent component

interface TabProps {
  active: boolean;
}

export const Tab: React.FC<TabProps> = ({ active }) => {
  // https://storybook.js.org/docs/addons/addons-api#useparameter
  const paramData = useParameter<string>(PARAM_KEY, '');

  return active ?  : null;
};
```

Addons with a UI must use the same React version as Storybook. If your component library uses a different React version, you must use addons that are built and published as standalone packages. We'll cover how to do this with the [Addon Kit](https://github.com/storybookjs/addon-kit).

## Setup

To create your first addon, you're going to use the [Addon Kit](https://github.com/storybookjs/addon-kit), a ready-to-use template featuring all the required building blocks, dependencies and configurations to help you get started building your addon. In the Addon Kit repository, click the **Use this template** button to create a new repository based on the Addon Kit's code.

Clone the repository you just created and install its dependencies. When the installation process finishes, you will be prompted with questions to configure your addon. Answer them, and when you're ready to start building your addon, run the following command to start Storybook in development mode and develop your addon in watch mode:

```sh
npm run start
```

```shell
pnpm run start
```

```sh
yarn start
```

The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use
JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript.

### Understanding the build system

Addons built in the Storybook ecosystem rely on [tsup](https://tsup.egoist.dev/), a fast, zero-config bundler powered by [esbuild](https://esbuild.github.io/) to transpile your addon's code into modern JavaScript that can run in the browser. Out of the box, the Addon Kit comes with a pre-configured `tsup` configuration file that you can use to customize the build process of your addon.

When the build scripts run, it will look for the configuration file and pre-bundle the addon's code based on the configuration provided. Addons can interact with Storybook in various ways. They can define presets to modify the configuration, add behavior to the manager UI, or add behavior to the preview iframe. These different use cases require different bundle outputs because they target different runtimes and environments. Presets are executed in a Node environment. Storybook's manager and preview environments provide certain packages in the global scope, so addons don't need to bundle them or include them as dependencies in their `package.json` file.

The `tsup` configuration handles these complexities by default, but you can customize it according to their requirements. For a detailed explanation of the bundling techniques used, please refer to [the README of the addon-kit](https://github.com/storybookjs/addon-kit#bundling), and check out the default `tsup` configuration [here](https://github.com/storybookjs/addon-kit/blob/main/tsup.config.ts).

## Register the addon

By default, code for the UI-based addons is located in one of the following files, depending on the type of addon built: **`src/Tool.tsx`**, **`src/Panel.tsx`**, or **`src/Tab.tsx`**. Since we're building a toolbar addon, we can safely remove the `Panel` and `Tab` files and update the remaining file to the following:

```tsx
// src/Tool.tsx

export const Tool = memo(function MyAddonSelector() {
  const [globals, updateGlobals] = useGlobals();
  const api = useStorybookApi();

  const isActive = [true, 'true'].includes(globals[PARAM_KEY]);

  const toggleMyTool = useCallback(() => {
    updateGlobals({
      [PARAM_KEY]: !isActive,
    });
  }, [isActive]);

  useEffect(() => {
    api.setAddonShortcut(ADDON_ID, {
      label: 'Toggle Addon [8]',
      defaultShortcut: ['8'],
      actionName: 'myaddon',
      showInMenu: false,
      action: toggleMyTool,
    });
  }, [toggleMyTool, api]);

  return (
    
      
    
  );
});
```

Going through the code blocks in sequence:

```ts title="src/Tool.tsx"

```

The [`useGlobals`](https://storybook.js.org/docs/addons/addons-api.md#useglobals) and [`useStorybookApi`](https://storybook.js.org/docs/addons/addons-api.md#usestorybookapi) hooks from the `manager-api` package are used to access the Storybook's APIs, allowing users to interact with the addon, such as enabling or disabling it.

The `Button` component from the `storybook/internal/components` module can be used to render the buttons in the toolbar. The [`@storybook/icons`](https://github.com/storybookjs/icons) package provides a large set of appropriately sized and styled icons to choose from.

```ts title="src/Tool.tsx"
export const Tool = memo(function MyAddonSelector() {
  const [globals, updateGlobals] = useGlobals();
  const api = useStorybookApi();

  const isActive = [true, 'true'].includes(globals[PARAM_KEY]);

  const toggleMyTool = useCallback(() => {
    updateGlobals({
      [PARAM_KEY]: !isActive,
    });
  }, [isActive]);

  useEffect(() => {
    api.setAddonShortcut(ADDON_ID, {
      label: 'Toggle Addon [8]',
      defaultShortcut: ['8'],
      actionName: 'myaddon',
      showInMenu: false,
      action: toggleMyTool,
    });
  }, [toggleMyTool, api]);

  return (
    
      
    
  );
});
```

The `Tool` component is the entry point of the addon. It renders the UI elements in the toolbar, registers a keyboard shortcut, and handles the logic to enable and disable the addon.

Moving onto the manager, here we register the addon with Storybook using a unique name and identifier. Since we've removed the `Panel` and `Tab` files, we'll need to adjust the file to only reference the addon we're building.

```ts
// src/manager.ts

// Register the addon
addons.register(ADDON_ID, () => {
  // Register the tool
  addons.add(TOOL_ID, {
    type: types.TOOL,
    title: 'My addon',
    match: ({ tabId, viewMode }) => !tabId && viewMode === 'story',
    render: Tool,
  });
});
```

### Conditionally render the addon

Notice the `match` property. It allows you to control the view mode (story or docs) and tab (the story canvas or [custom tabs](https://storybook.js.org/docs/addons/addon-types.md#tabs)) where the toolbar addon is visible. For example:

- `({ tabId }) => tabId === 'my-addon/tab'` will show your addon when viewing the tab with the ID `my-addon/tab`.
- `({ viewMode }) => viewMode === 'story'` will show your addon when viewing a story in the canvas.
- `({ viewMode }) => viewMode === 'docs'` will show your addon when viewing the documentation for a component.
- `({ tabId, viewMode }) => !tabId && viewMode === 'story'` will show your addon when viewing a story in the canvas and not in a custom tab (i.e. when `tabId === undefined`).

Run the `start` script to build and start Storybook and verify that the addon is registered correctly and showing in the UI.

![Addon registered in the toolbar](../_assets/addons/storybook-addon-initial-state.png)

### Style the addon

In Storybook, applying styles for addons is considered a side-effect. Therefore, we'll need to make some changes to our addon to allow it to use the styles when it is active and remove them when it's disabled. We're going to rely on two of Storybook's features to handle this: [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) and [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals). To handle the CSS logic, we must include some helper functions to inject and remove the stylesheets from the DOM. Start by creating the helper file with the following content:

```ts
// src/helpers.ts

export const clearStyles = (selector: string | string[]) => {
  const selectors = Array.isArray(selector) ? selector : [selector];
  selectors.forEach(clearStyle);
};

const clearStyle = (input: string | string[]) => {
  const selector = typeof input === 'string' ? input : input.join('');
  const element = global.document.getElementById(selector);
  if (element && element.parentElement) {
    element.parentElement.removeChild(element);
  }
};

export const addOutlineStyles = (selector: string, css: string) => {
  const existingStyle = global.document.getElementById(selector);
  if (existingStyle) {
    if (existingStyle.innerHTML !== css) {
      existingStyle.innerHTML = css;
    }
  } else {
    const style = global.document.createElement('style');
    style.setAttribute('id', selector);
    style.innerHTML = css;
    global.document.head.appendChild(style);
  }
};
```

Next, create the file with the styles we want to inject with the following content:

```ts
// src/OutlineCSS.ts

export default function outlineCSS(selector: string) {
  return dedent /* css */ `
    ${selector} body {
      outline: 1px solid #2980b9 !important;
    }

    ${selector} article {
      outline: 1px solid #3498db !important;
    }

    ${selector} nav {
      outline: 1px solid #0088c3 !important;
    }

    ${selector} aside {
      outline: 1px solid #33a0ce !important;
    }

    ${selector} section {
      outline: 1px solid #66b8da !important;
    }

    ${selector} header {
      outline: 1px solid #99cfe7 !important;
    }

    ${selector} footer {
      outline: 1px solid #cce7f3 !important;
    }

    ${selector} h1 {
      outline: 1px solid #162544 !important;
    }

    ${selector} h2 {
      outline: 1px solid #314e6e !important;
    }

    ${selector} h3 {
      outline: 1px solid #3e5e85 !important;
    }

    ${selector} h4 {
      outline: 1px solid #449baf !important;
    }

    ${selector} h5 {
      outline: 1px solid #c7d1cb !important;
    }

    ${selector} h6 {
      outline: 1px solid #4371d0 !important;
    }

    ${selector} main {
      outline: 1px solid #2f4f90 !important;
    }

    ${selector} address {
      outline: 1px solid #1a2c51 !important;
    }

    ${selector} div {
      outline: 1px solid #036cdb !important;
    }

    ${selector} p {
      outline: 1px solid #ac050b !important;
    }

    ${selector} hr {
      outline: 1px solid #ff063f !important;
    }

    ${selector} pre {
      outline: 1px solid #850440 !important;
    }

    ${selector} blockquote {
      outline: 1px solid #f1b8e7 !important;
    }

    ${selector} ol {
      outline: 1px solid #ff050c !important;
    }

    ${selector} ul {
      outline: 1px solid #d90416 !important;
    }

    ${selector} li {
      outline: 1px solid #d90416 !important;
    }

    ${selector} dl {
      outline: 1px solid #fd3427 !important;
    }

    ${selector} dt {
      outline: 1px solid #ff0043 !important;
    }

    ${selector} dd {
      outline: 1px solid #e80174 !important;
    }

    ${selector} figure {
      outline: 1px solid #ff00bb !important;
    }

    ${selector} figcaption {
      outline: 1px solid #bf0032 !important;
    }

    ${selector} table {
      outline: 1px solid #00cc99 !important;
    }

    ${selector} caption {
      outline: 1px solid #37ffc4 !important;
    }

    ${selector} thead {
      outline: 1px solid #98daca !important;
    }

    ${selector} tbody {
      outline: 1px solid #64a7a0 !important;
    }

    ${selector} tfoot {
      outline: 1px solid #22746b !important;
    }

    ${selector} tr {
      outline: 1px solid #86c0b2 !important;
    }

    ${selector} th {
      outline: 1px solid #a1e7d6 !important;
    }

    ${selector} td {
      outline: 1px solid #3f5a54 !important;
    }

    ${selector} col {
      outline: 1px solid #6c9a8f !important;
    }

    ${selector} colgroup {
      outline: 1px solid #6c9a9d !important;
    }

    ${selector} button {
      outline: 1px solid #da8301 !important;
    }

    ${selector} datalist {
      outline: 1px solid #c06000 !important;
    }

    ${selector} fieldset {
      outline: 1px solid #d95100 !important;
    }

    ${selector} form {
      outline: 1px solid #d23600 !important;
    }

    ${selector} input {
      outline: 1px solid #fca600 !important;
    }

    ${selector} keygen {
      outline: 1px solid #b31e00 !important;
    }

    ${selector} label {
      outline: 1px solid #ee8900 !important;
    }

    ${selector} legend {
      outline: 1px solid #de6d00 !important;
    }

    ${selector} meter {
      outline: 1px solid #e8630c !important;
    }

    ${selector} optgroup {
      outline: 1px solid #b33600 !important;
    }

    ${selector} option {
      outline: 1px solid #ff8a00 !important;
    }

    ${selector} output {
      outline: 1px solid #ff9619 !important;
    }

    ${selector} progress {
      outline: 1px solid #e57c00 !important;
    }

    ${selector} select {
      outline: 1px solid #e26e0f !important;
    }

    ${selector} textarea {
      outline: 1px solid #cc5400 !important;
    }

    ${selector} details {
      outline: 1px solid #33848f !important;
    }

    ${selector} summary {
      outline: 1px solid #60a1a6 !important;
    }

    ${selector} command {
      outline: 1px solid #438da1 !important;
    }

    ${selector} menu {
      outline: 1px solid #449da6 !important;
    }

    ${selector} del {
      outline: 1px solid #bf0000 !important;
    }

    ${selector} ins {
      outline: 1px solid #400000 !important;
    }

    ${selector} img {
      outline: 1px solid #22746b !important;
    }

    ${selector} iframe {
      outline: 1px solid #64a7a0 !important;
    }

    ${selector} embed {
      outline: 1px solid #98daca !important;
    }

    ${selector} object {
      outline: 1px solid #00cc99 !important;
    }

    ${selector} param {
      outline: 1px solid #37ffc4 !important;
    }

    ${selector} video {
      outline: 1px solid #6ee866 !important;
    }

    ${selector} audio {
      outline: 1px solid #027353 !important;
    }

    ${selector} source {
      outline: 1px solid #012426 !important;
    }

    ${selector} canvas {
      outline: 1px solid #a2f570 !important;
    }

    ${selector} track {
      outline: 1px solid #59a600 !important;
    }

    ${selector} map {
      outline: 1px solid #7be500 !important;
    }

    ${selector} area {
      outline: 1px solid #305900 !important;
    }

    ${selector} a {
      outline: 1px solid #ff62ab !important;
    }

    ${selector} em {
      outline: 1px solid #800b41 !important;
    }

    ${selector} strong {
      outline: 1px solid #ff1583 !important;
    }

    ${selector} i {
      outline: 1px solid #803156 !important;
    }

    ${selector} b {
      outline: 1px solid #cc1169 !important;
    }

    ${selector} u {
      outline: 1px solid #ff0430 !important;
    }

    ${selector} s {
      outline: 1px solid #f805e3 !important;
    }

    ${selector} small {
      outline: 1px solid #d107b2 !important;
    }

    ${selector} abbr {
      outline: 1px solid #4a0263 !important;
    }

    ${selector} q {
      outline: 1px solid #240018 !important;
    }

    ${selector} cite {
      outline: 1px solid #64003c !important;
    }

    ${selector} dfn {
      outline: 1px solid #b4005a !important;
    }

    ${selector} sub {
      outline: 1px solid #dba0c8 !important;
    }

    ${selector} sup {
      outline: 1px solid #cc0256 !important;
    }

    ${selector} time {
      outline: 1px solid #d6606d !important;
    }

    ${selector} code {
      outline: 1px solid #e04251 !important;
    }

    ${selector} kbd {
      outline: 1px solid #5e001f !important;
    }

    ${selector} samp {
      outline: 1px solid #9c0033 !important;
    }

    ${selector} var {
      outline: 1px solid #d90047 !important;
    }

    ${selector} mark {
      outline: 1px solid #ff0053 !important;
    }

    ${selector} bdi {
      outline: 1px solid #bf3668 !important;
    }

    ${selector} bdo {
      outline: 1px solid #6f1400 !important;
    }

    ${selector} ruby {
      outline: 1px solid #ff7b93 !important;
    }

    ${selector} rt {
      outline: 1px solid #ff2f54 !important;
    }

    ${selector} rp {
      outline: 1px solid #803e49 !important;
    }

    ${selector} span {
      outline: 1px solid #cc2643 !important;
    }

    ${selector} br {
      outline: 1px solid #db687d !important;
    }

    ${selector} wbr {
      outline: 1px solid #db175b !important;
    }`;
}
```

Since the addon can be active in both the story and documentation modes, the DOM node for Storybook's preview `iframe` is different in these two modes. In fact, Storybook renders multiple story previews on one page when in documentation mode. Therefore, we'll need to choose the correct selector for the DOM node where the styles will be injected and ensure the CSS is scoped to that particular selector. That mechanism is provided as an example within the `src/withGlobals.ts` file, which we'll use to connect the styling and helper functions to the addon logic. Update the file to the following:

```ts
// src/withGlobals.ts

  Renderer,
  PartialStoryFn as StoryFunction,
  StoryContext,
} from 'storybook/internal/types';

export const withGlobals = (StoryFn: StoryFunction<Renderer>, context: StoryContext<Renderer>) => {
  const [globals] = useGlobals();

  const isActive = [true, 'true'].includes(globals[PARAM_KEY]);

  // Is the addon being used in the docs panel
  const isInDocs = context.viewMode === 'docs';

  const outlineStyles = useMemo(() => {
    const selector = isInDocs
      ? `#anchor--${context.id} .docs-story, #anchor--primary--${context.id} .docs-story`
      : '.sb-show-main';

    return outlineCSS(selector);
  }, [context.id]);
  useEffect(() => {
    const selectorId = isInDocs ? `my-addon-docs-${context.id}` : `my-addon`;

    if (!isActive) {
      clearStyles(selectorId);
      return;
    }

    addOutlineStyles(selectorId, outlineStyles);

    return () => {
      clearStyles(selectorId);
    };
  }, [isActive, outlineStyles, context.id]);

  return StoryFn();
};
```

## Packaging and publishing

Storybook addons, similar to most packages in the JavaScript ecosystem, are distributed as NPM packages. However, they have specific criteria that need to be met to be published to NPM and crawled by the integration catalog:

1. Have a `dist` folder with the transpiled code.
2. A `package.json` file declaring:
   - Module-related information
   - Integration catalog metadata

### Module Metadata

The first category of metadata is related to the addon itself. This includes the entry for the module, which files to include when the addon is published. And the required configuration to integrate the addon with Storybook, allowing it to be used by its consumers.

```json title="package.json"
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "node": "./dist/index.js",
      "require": "./dist/index.js",
      "import": "./dist/index.mjs"
    },
    "./manager": "./dist/manager.mjs",
    "./preview": "./dist/preview.mjs",
    "./package.json": "./package.json"
  },
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "files": ["dist/**/*", "README.md", "*.js", "*.d.ts"],
  "devDependencies": {
    "@storybook/addon-docs": "^9.0.0",
    "storybook": "^9.0.0"
  },
  "bundler": {
    "exportEntries": ["src/index.ts"],
    "managerEntries": ["src/manager.ts"],
    "previewEntries": ["src/preview.ts"]
  }
}
```

### Integration Catalog Metadata

The second metadata category is related to the [integration catalog](https://storybook.js.org/integrations). Most of this information is already pre-configured by the Addon Kit. However, items like the display name, icon, and frameworks must be configured via the `storybook` property to be displayed in the catalog.

```json title="package.json"
{
  "name": "my-storybook-addon",
  "version": "1.0.0",
  "description": "My first storybook addon",
  "author": "Your Name",
  "storybook": {
    "displayName": "My Storybook Addon",
    "unsupportedFrameworks": ["react-native"],
    "icon": "https://yoursite.com/link-to-your-icon.png"
  },
  "keywords": ["storybook-addon", "appearance", "style", "css", "layout", "debug"]
}
```

The `storybook` configuration element includes additional properties that help customize the
addon's searchability and indexing. For more information, see the [Integration catalog
documentation](https://storybook.js.org/docs/addons/integration-catalog.md).

One essential item to note is the `keywords` property as it maps to the catalog's tag system. Adding the `storybook-addon` keyword ensures that the addon is discoverable in the catalog when searching for addons. The remaining keywords help with the searchability and categorization of the addon.

### Publishing to NPM

Once you're ready to publish your addon to NPM, the Addon Kit comes pre-configured with the [Auto](https://github.com/intuit/auto) package for release management. It generates a changelog and uploads the package to NPM and GitHub automatically. Therefore, you need to configure access to both.

1. Authenticate using [npm adduser](https://docs.npmjs.com/cli/v9/commands/npm-adduser)
2. Generate a [access token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-access-tokens) with both `read` and `publish` permissions.
3. Create a [personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` and `workflow` scoped permissions.
4. Create a `.env` file in the root of your project and add the following:

```plaintext
GH_TOKEN=value_you_just_got_from_github
NPM_TOKEN=value_you_just_got_from_npm
```

Next, run the following command to create labels on GitHub. You'll use these labels to categorize changes to the package.

```shell
npx auto create-labels
```

Finally, run the following command to create a release for your addon. This will build and package the addon code, bump the version, push the release into GitHub and npm, and generate a changelog.

```shell
npm run release
```

```shell
pnpm run release
```

```shell
yarn release
```

### CI automation

By default, the Addon Kit comes pre-configured with a GitHub Actions workflow, enabling you to automate the release management process. This ensures that the package is always up to date with the latest changes and that the changelog is updated accordingly. However, you'll need additional configuration to use your NPM and GitHub tokens to publish the package successfully. In your repository, click the **Settings** tab, then the **Secrets and variables** dropdown, followed by the **Actions** item. You should see the following screen:

![GitHub secrets page](../_assets/addons/github-secrets-screen.png)

Then, click the **New repository secret**, name it `NPM_TOKEN`, and paste the token you generated earlier. Whenever you merge a pull request to the default branch, the workflow will run and publish a new release, automatically incrementing the version number and updating the changelog.

**Learn more about the Storybook addon ecosystem**

- [Types of addons](https://storybook.js.org/docs/addons/addon-types.md) for other types of addons
- Writing addons for the basics of addon development
- [Presets](https://storybook.js.org/docs/addons/writing-presets.md) for preset development
- [Integration catalog](https://storybook.js.org/docs/addons/integration-catalog.md) for requirements and available recipes
- [API reference](https://storybook.js.org/docs/addons/addons-api.md) to learn about the available APIs
> Source: https://storybook.js.org/docs/addons/writing-addons
---

# Configure and communicate with an addon

The addon API is designed for customization. It offers addon authors different ways to configure and communicate with their users' Storybook. Let's look at what these are and their suggested use cases.

## Preset

Presets offload the burden of configuration from the user to the addon. Preset options are global and are accessible from NodeJS. They're ideal for pre-configuring Webpack loaders, Babel plugins, and other library or framework-specific configurations.

For example, many libraries require that the app be wrapped by a `Provider` which _provides_ data to components down the tree. Presets can describe behavior like adding wrappers automatically, without users having to do any manual configuration. If a user installs an addon that has Presets, the addon can instruct Storybook to wrap all stories in `Provider`. This allows folks to start using your library with Storybook with a single line of config.

For more on presets, see: [Write a preset addon](https://storybook.js.org/docs/addons/writing-presets.md)

The mechanism for wrapping each story is referred to as a Storybook [decorator](https://storybook.js.org/docs/writing-stories/decorators.md). They allow you to augment stories with extra rendering functionality or by providing data.

## Parameters

Parameters are available in the browser and are great for configuring addon behavior globally, at the component level, or at the story level.

For example, the [Pseudo States addon](https://storybook.js.org/addons/storybook-addon-pseudo-states) uses parameters to enable the various pseudo-states. Users can provide global defaults and then override them at the story level.

Use the [`useParameter`](https://storybook.js.org/docs/addons/addons-api.md#useparameter) hook to access the parameter values within your addon.

```js
export const Hover = {
  render: () => Label,
  parameters: { pseudo: { hover: true } },
};
```

## Channels

Channels enable two-way communication between the manager and the preview pane, using a NodeJS [EventEmitter](https://nodejs.org/api/events.html) compatible API. Your addons can plug into specific channels and respond to these events.

For example, [Actions](https://storybook.js.org/docs/essentials/actions) captures user events and displays their data in a panel.

Use the [`useChannel`](https://storybook.js.org/docs/addons/addons-api.md#usechannel) hook to access the channel data within your addon.

For a complete example, check out [storybookjs/addon-kit/withRoundTrip.ts](https://github.com/storybookjs/addon-kit/blob/main/src/withRoundTrip.ts)
> Source: https://storybook.js.org/docs/addons/configure-addons
---

# Write a preset addon

Storybook presets are pre-configured settings or configurations that enable developers quickly set up and customize their environment with a specific set of features, functionalities, or integrations.

## How presets work

Preset addons allow developers to compose various configuration options and plugins via APIs to integrate with Storybook and customize its behavior and functionality. Typically, presets are separated into two files, each with its specific role.

### Local presets

This type of preset allows you to encapsulate and organize configurations specific to the addon, including [builder](https://storybook.js.org/docs/builders.md) support, [Babel](https://babeljs.io/), or third-party integrations. For example:

```ts
// example-addon/src/preset.ts

export const webpackFinal = webpack as any;

export const viteFinal = vite as any;

export const babelDefault = babel as any;
```

### Root-level presets

This type of preset is user-facing and responsible for registering the addon without any additional configuration from the user by bundling Storybook-related features (e.g., [parameters](https://storybook.js.org/docs/writing-stories/parameters.md)) via the [`previewAnnotations`](https://storybook.js.org/docs/api/main-config/main-config-preview-annotations.md) and UI related features (e.g., addons) via the `managerEntries` API. For example:

```js
// example-addon/preset.js
export const previewAnnotations = [import.meta.resolve('./dist/preview')];

export const managerEntries = [import.meta.resolve('./dist/manager')];

export * from './dist/preset.js';
```

## Presets API

When writing a preset, you can access a select set of APIs to interact with the Storybook environment, including the supported builders (e.g., Webpack, Vite), the Storybook configuration, and UI. Below are the available APIs you can use when writing a preset addon.

### Babel

To customize Storybook's Babel configuration and add support for additional features, you can use the [`babelDefault`](https://storybook.js.org/docs/api/main-config/main-config-babel-default.md) API. It will apply the provided configuration ahead of any other user presets, which can be further customized by the end user via the [`babel`](https://storybook.js.org/docs/api/main-config/main-config-babel.md) configuration option. For example:

```ts
// example-addon/src/babel/babelDefault.ts

export function babelDefault(config: TransformOptions) {
  return {
    ...config,
    plugins: [
      ...config.plugins,
      [import.meta.resolve('@babel/plugin-transform-react-jsx'), {}, 'preset'],
    ],
  };
}
```

The Babel configuration is only applied to frameworks that use Babel internally. If you enable it for a framework that uses a different compiler, like [SWC](https://swc.rs/) or [esbuild](https://esbuild.github.io/), it will be ignored.

### Builders

By default, Storybook provides support for the leading industry builders, including [Webpack](https://storybook.js.org/docs/builders/webpack.md) and [Vite](https://storybook.js.org/docs/builders/vite.md). If you need additional features for any of these builders, you can use APIs to extend the builder configuration based on your specific needs.

#### Vite

If you are creating a preset and want to include Vite support, the `viteFinal` API can be used to modify the default configuration and enable additional features. For example:

```ts
// example-addon/src/vite/viteFinal.ts
export function ViteFinal(config: any, options: any = {}) {
  config.plugins.push(
    new MyCustomPlugin({
      someOption: true,
    }),
  );

  return config;
}
```

#### Webpack

To customize the Webpack configuration in Storybook to add support for additional file types, apply specific loaders, configure plugins, or make any other necessary modifications, you can use the `webpackFinal` API. Once invoked, it will extend the default Webpack configuration with the provided configuration. An example of this would be:

```ts
// example-addon/src/webpack/webpackFinal.ts

export function webpackFinal(config: WebpackConfig, options: any = {}) {
  const rules = [
    ...(config.module?.rules || []),
    {
      test: /\.custom-file$/,
      loader: fileURLToPath(import.meta.resolve(`custom-loader`)),
    },
  ];
  config.module.rules = rules;

  return config;
}
```

### ManagerEntries

If you're writing a preset that loads third-party addons, which you may not have control over, but require access to specific features or additional configuration, you can use the `managerEntries` API. For example:

```js
// example-addon/preset.js
export const managerEntries = (entry = []) => {
  return [...entry, import.meta.resolve('path-to-third-party-addon')];
};
```

### PreviewAnnotations

If you need additional settings to render stories for a preset, like [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) or [parameters](https://storybook.js.org/docs/writing-stories/parameters.md), you can use the `previewAnnotations` API. For example, to apply a decorator to all stories, create a preview file that includes the decorator and make it available to the preset as follows:

```ts
// example-addon/src/preview.ts|tsx — CSF 3

const preview: ProjectAnnotations<Renderer> = {
  decorators: [CustomDecorator],
  globals: {
    [PARAM_KEY]: false,
  },
};

export default preview;
```

```ts
// example-addon/src/preview.tsx — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  decorators: [CustomDecorator],
  globals: {
    [PARAM_KEY]: false,
  },
});
```

## Advanced configuration

The presets API is designed to be flexible and allow you to customize Storybook to your specific needs, including using presets for more advanced use cases without publishing them. In such cases, you can rely on a private preset. These private presets contain configuration options meant for development purposes and not for end-users. The `.storybook/main.js|ts` file is an example of such a private preset that empowers you to modify the behavior and functionality of Storybook.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, angular, etc.

const config: StorybookConfig = {
  viteFinal: async (config, options) => {
    // Update config here
    return config;
  },
  webpackFinal: async (config, options) => {
    // Change webpack config
    return config;
  },
  babel: async (config, options) => {
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  viteFinal: async (config, options) => {
    // Update config here
    return config;
  },
  webpackFinal: async (config, options) => {
    // Change webpack config
    return config;
  },
  babel: async (config, options) => {
    return config;
  },
});
```

### Addons

For addon consumers, the [`managerEntries`](#managerentries) API can be too technical, making it difficult to use. To make it easier to add addons to Storybook, the preset API provides the [`addons`](https://storybook.js.org/docs/api/main-config/main-config-addons.md) API, which accepts an array of addon names and will automatically load them for you. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  addons: [
    // Other Storybook addons
    '@storybook/addon-a11y',
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  addons: [
    // Other Storybook addons
    '@storybook/addon-a11y',
  ],
});
```

The array of values supports references to additional presets and addons that should be included in the manager. Storybook will automatically detect whether the provided value is a preset or an addon and load it accordingly.

### Entries

Entries are the place to register entry points for the preview. This feature can be utilized to create a configure-storybook preset that automatically loads all `*.stories.js` files into Storybook, eliminating the need for users to copy-paste the same configuration repeatedly.

### UI configuration

The Storybook preset API also provides access to the UI configuration, including the `head` and `body` HTML elements of the preview, configured by the [`previewHead`](https://storybook.js.org/docs/api/main-config/main-config-preview-head.md) and [`previewBody`](https://storybook.js.org/docs/api/main-config/main-config-preview-body.md) APIs. Both allow you to set up Storybook in a way that is similar to using the [`preview-head.html`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-head) and [`preview-body.html`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-body) files. These methods accept a string and return a modified version, injecting the provided content into the HTML element.

```ts
// .storybook/main.ts — Body (CSF 3)
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  previewBody: (body) => `
    ${body}
    ${
      process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
    }
  `,
};

export default config;
```

```ts
// .storybook/main.ts — Head (CSF 3)
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  previewHead: (head) => `
    ${head}
    <style>
      html, body {
        background: #827979;
      }
    </style>
 `,
};

export default config;
```

```ts
// .storybook/main.ts — Body (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  previewBody: (body) => `
    ${body}
    ${
      process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
    }
  `,
});
```

```ts
// .storybook/main.ts — Head (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  previewHead: (head) => `
    ${head}
    <style>
      html, body {
        background: #827979;
      }
    </style>
 `,
});
```

Additionally, if you need to customize the manager (i.e., where Storybook’s search, navigation, toolbars, and addons render), you can use the [`managerHead`](https://storybook.js.org/docs/api/main-config/main-config-manager-head.md) to modify the UI, similar to how you would do it with the `manager-head.html` file. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  managerHead: (head) => `
    ${head}
    <link rel="icon" type="image/png" href="/logo192.png" sizes="192x192" />
  `,
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  managerHead: (head) => `
    ${head}
    <link rel="icon" type="image/png" href="/logo192.png" sizes="192x192" />
  `,
});
```

However, if you need, you can also customize the template used by Storybook to render the UI. To do so, you can use the `previewMainTemplate` API and provide a reference for a custom template created as a `ejs` file. For an example of how to do this, see the [template](https://github.com/storybookjs/storybook/blob/next/code/builders/builder-webpack5/templates/preview.ejs) used by the Webpack 5 builder.

## Troubleshooting

### Storybook doesn't load files in my preset

As Storybook relies on [esbuild](https://esbuild.github.io/) instead of Webpack to build the UI, presets that depend on the `managerWebpack` API to configure the manager or load additional files other than CSS or images will no longer work. We recommend removing it from your preset and adjusting your configuration to convert any additional files to JavaScript.

**Learn more about the Storybook addon ecosystem**

- [Types of addons](https://storybook.js.org/docs/addons/addon-types.md) for other types of addons
- [Writing addons](https://storybook.js.org/docs/addons/writing-addons.md) for the basics of addon development
- Presets for preset development
- [Integration catalog](https://storybook.js.org/docs/addons/integration-catalog.md) for requirements and available recipes
- [API reference](https://storybook.js.org/docs/addons/addons-api.md) to learn about the available APIs
> Source: https://storybook.js.org/docs/addons/writing-presets
---

# Add to the integration catalog

Storybook has two types of integrations, addons and recipes, which are listed in the [integration catalog](https://storybook.js.org/integrations/).

## Addons

Storybook addons are distributed via npm. The catalog is populated by querying npm's registry for Storybook-specific metadata in `package.json`.

Add your addon to the catalog by publishing a npm package that follows these requirements:

- `package.json` with [module information](https://storybook.js.org/docs/addons/writing-addons.md#setup) and [addon metadata](#addon-metadata)
- `README.md` file with installation and configuration instructions
- `/dist` directory containing transpiled ES5 code
- `preset.js` file written as an ES5 module at the root level

Get a refresher on how to [write a Storybook addon](https://storybook.js.org/docs/addons/writing-addons.md).

### Addon metadata

We rely on metadata to organize your addon in the catalog. You must add the <code>storybook-addon</code> as the first keyword, followed by your addon's category. Additional keywords will be used in search and as tags.

| Property      | Description                            | Example                                                                   |
| ------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| `name`        | Addon package name                     | storybook-addon-example                                                   |
| `description` | Addon description                      | Outline all elements with CSS to help with layout placement and alignment |
| `author`      | Name of the author                     | winkerVSbecks                                                             |
| `keywords`    | List of keywords to describe the addon | `["storybook-addon","style","debug"]`                                     |
| `repository`  | Addon repository                       | `{"type": "git","url": "https://github.com/someone/my-addon" }`           |

Customize your addon's appearance by adding the `storybook` property with the following fields.

| Property                | Description                                               | Example                             |
| ----------------------- | --------------------------------------------------------- | ----------------------------------- |
| `displayName`           | Display name                                              | Example                             |
| `icon`                  | Link to custom icon for the addon (SVG are not supported) | https://yoursite.com/addon-icon.png |
| `unsupportedFrameworks` | List of unsupported frameworks                            | `["vue"]`                           |
| `supportedFrameworks`   | List of supported frameworks                              | `["react", "angular"]`              |

Use the list below as a reference when filling in the values for both the `supportedFrameworks` and `unsupportedFrameworks` fields.

- react
- vue
- angular
- web-components
- ember
- html
- svelte
- preact
- react-native

Make sure to copy each item **exactly** as listed so that we can properly index your addon in our catalog.

```json title="package.json"
{
  "name": "storybook-addon-example",
  "version": "1.0.0",
  "description": "Outline all elements with CSS to help with layout placement and alignment",
  "repository": {
    "type": "git",
    "url": "https://github.com/chromaui/storybook-addon-example"
  },
  "author": "winkerVSbecks",
  "keywords": ["storybook-addon", "style", "debug", "layout", "css"],
  "storybook": {
    "displayName": "Outline",
    "unsupportedFrameworks": ["vue"],
    "supportedFrameworks": ["react", "angular"],
    "icon": "https://yoursite.com/addon-icon.png"
  }
}
```

The `package.json` above appears like below in the catalog. See an example of a production package.json [here](https://github.com/chromaui/storybook-outline/blob/main/package.json).

![Storybook addon in the catalog](../_assets/addons/addon-display.png)

#### How long does it take for my addon to show up in the catalog?

Once you publish the addon, it will appear in the catalog. There may be a delay between the time you publish your addon and when it's listed in the catalog. If your addon doesn't show up within 24 hours, [open an issue](https://github.com/storybookjs/frontpage/issues).

## Recipes

Recipes are a set of instructions to integrate third-party libraries into Storybook in cases where an addon does not exist or the integration requires some manual effort.

### Who owns them?

Recipes are written and maintained by the Storybook team. We create recipes based on community popularity, tool maturity, and stability of the integration. Our goal is to ensure that recipes continue to work over time.

Not finding the recipe that you want? If it's popular in the community, our docs team will write one. In the mean time, try searching for a solution — it's likely that someone has the same requirements as you do. You can also help us out by writing recipes on your own site which speeds up the research process.

### Request a recipe

If you'd like to request a recipe, open a [new discussion](https://github.com/storybookjs/storybook/discussions/new?category=ideas) in our GitHub repo. We'll review your request, and if it's popular, we'll add it to our backlog and prioritize it.

**Learn more about the Storybook addon ecosystem**

- [Types of addons](https://storybook.js.org/docs/addons/addon-types.md) for other types of addons
- [Writing addons](https://storybook.js.org/docs/addons/writing-addons.md) for the basics of addon development
- [Presets](https://storybook.js.org/docs/addons/writing-presets.md) for preset development
- Integration catalog for requirements and available recipes
- [API reference](https://storybook.js.org/docs/addons/addons-api.md) to learn about the available APIs
> Source: https://storybook.js.org/docs/addons/integration-catalog
---

# Types of addons

Each Storybook addon is classified into two general categories, UI-based or Presets. Each type of addons feature is documented here. Use this as a reference when creating your addon.

## UI-based addons

UI-based addons allow you to customize Storybook's UI with the following elements.

### Panels

Panel addons allow you to add your own UI in Storybook's addon panel. This is the most common type of addon in the ecosystem. For example, the official [`@storybook/addon-a11y`](https://github.com/storybookjs/storybook/tree/next/code/addons/a11y) uses this pattern.

![Storybook panel](../_assets/addons/storybook-panel.png)

Use this boilerplate code to add a new `Panel` to Storybook's UI:

```js
// addon-panel/manager.js

addons.register('my/panel', () => {
  addons.add('my-panel-addon/panel', {
    title: 'Example Storybook panel',
    //👇 Sets the type of UI element in Storybook
    type: types.PANEL,
    render: ({ active }) => (
      
        <h2>I'm a panel addon in Storybook</h2>
      
    ),
  });
});
```

### Toolbars

Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. For example, the official [`@storybook/addon-themes`](https://storybook.js.org/addons/@storybook/addon-themes) uses this pattern.

![Storybook toolbar addon](../_assets/addons/storybook-toolbar.png)

Use this boilerplate code to add a new `button` to Storybook's Toolbar:

```js
// addon-toolbar/manager.js

addons.register('my-addon', () => {
  addons.add('my-addon/toolbar', {
    title: 'Example Storybook toolbar',
    //👇 Sets the type of UI element in Storybook
    type: types.TOOL,
    //👇 Shows the Toolbar UI element if the story canvas is being viewed
    match: ({ tabId, viewMode }) => !tabId && viewMode === 'story',
    render: ({ active }) => (
      
        
      
    ),
  });
});
```

The `match` property allows you to conditionally render your toolbar addon, [based on the current view](https://storybook.js.org/docs/addons/writing-addons.md#conditionally-render-the-addon). The `icon` element used in the example loads the icons from the `storybook/internal/components` module. See [here](https://storybook.js.org/docs/faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use.

### Tabs

Tab addons allow you to create your own custom tabs in Storybook.

![Storybook tab addon](../_assets/addons/storybook-tab.png)

Use this boilerplate code to add a new `Tab` to Storybook's UI:

```js
// addon-tab/manager.js

addons.register('my-addon', () => {
  addons.add('my-addon/tab', {
    type: types.TAB,
    title: 'Example Storybook tab',
    render: () => (
      <div>
        <h2>I'm a tabbed addon in Storybook</h2>
      </div>
    ),
  });
});
```

Learn how to write your own addon that includes these UI elements [here](https://storybook.js.org/docs/addons/writing-addons.md).

## Preset addons

Storybook preset addons are grouped collections of `babel`, `webpack`, and `addons` configurations to integrate Storybook and other technologies. For example the official [preset-create-react-app](https://github.com/storybookjs/presets/tree/master/packages/preset-create-react-app).

Use this boilerplate code while writing your own preset addon.

```js
// .storybook/my-preset.js
export default {
  managerWebpack: async (config, options) => {
    // Update config here
    return config;
  },
  webpackFinal: async (config, options) => {
    return config;
  },
  babel: async (config, options) => {
    return config;
  },
};
```

**Learn more about the Storybook addon ecosystem**

- Types of addons for other types of addons
- [Writing addons](https://storybook.js.org/docs/addons/writing-addons.md) for the basics of addon development
- [Presets](https://storybook.js.org/docs/addons/writing-presets.md) for preset development
- [Integration catalog](https://storybook.js.org/docs/addons/integration-catalog.md) for requirements and available recipes
- [API reference](https://storybook.js.org/docs/addons/addons-api.md) to learn about the available APIs
> Source: https://storybook.js.org/docs/addons/addon-types
---

# Addon knowledge base

Once you understand the basics of writing addons, there are a variety of common enhancements to make your addon better. This page details additional information about addon creation. Use it as a quick reference guide when creating your own addons.

## Disable the addon panel

It’s possible to disable the addon panel for a particular story.

To make that possible, you need to pass the `paramKey` element when you register the panel:

```js
// /my-addon/manager.js
addons.register(ADDON_ID, () => {
  addons.add(PANEL_ID, {
    type: types.PANEL,
    title: 'My Addon',
    render: () => <div>Addon tab content</div>,
    paramKey: 'myAddon', // this element
  });
});
```

Then when adding a story, you can pass a disabled parameter.

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
  parameters: {
    myAddon: { disable: true }, // Disables the addon
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
  parameters: {
    myAddon: { disable: true }, // Disables the addon
  },
});
```

## Style your addon

Storybook uses [Emotion](https://emotion.sh/docs/introduction) for styling. Alongside with a theme that you can customize!

We recommend using Emotion to style your addon’s UI components. That allows you to use the active Storybook theme to deliver a seamless developer experience.
If you don’t want to use Emotion, you can use inline styles or another css-in-js lib. You can receive the theme as a prop by using Emotion's `withTheme` HOC. [Read more about theming](https://storybook.js.org/docs/configure/user-interface/theming.md).

## Storybook components

Addon authors can develop their UIs using any React library. But we recommend using Storybook’s UI components in `storybook/internal/components` to build addons faster. When you use Storybook components, you get:

- Battle-tested off-the-shelf components
- Storybook native look and feel
- Built-in support for Storybook theming

Use the components listed below with your next addon.

| Component          | Source                                                                                                                                                         | Story                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Action Bar         | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ActionBar/ActionBar.tsx)                 | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-actionbar--single-item)         |
| Addon Panel        | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/addon-panel/addon-panel.tsx)             | N/A                                                                                                                            |
| Badge              | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Badge/Badge.tsx)                         | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-badge--all-badges)              |
| Button             | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Button/Button.tsx)                       | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-button--all-buttons)            |
| Form               | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/form/index.tsx)                          | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-form-button--sizes)             |
| Loader             | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Loader/Loader.tsx)                       | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-loader--progress-bar)           |
| PlaceHolder        | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/placeholder/placeholder.tsx)             | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-placeholder--single-child)      |
| Scroll Area        | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ScrollArea/ScrollArea.tsx)               | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-scrollarea--vertical)           |
| Space              | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/spaced/Spaced.tsx)                       | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-spaced--row)                    |
| Syntax Highlighter | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/syntaxhighlighter/syntaxhighlighter.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-syntaxhighlighter--bash)        |
| Tabs               | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tabs/tabs.tsx)                           | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tabs--stateful-static)          |
| ToolBar            | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/bar/bar.tsx)                             | N/A                                                                                                                            |
| ToolTip            | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tooltip/Tooltip.tsx)                     | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tooltip-tooltip--basic-default) |
| Zoom               | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Zoom/Zoom.tsx)                           | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-zoom--element-actual-size)      |

Complementing the components, also included is a set of UI primitives. Use the content listed below as a reference for styling your addon.

| Component                      | Source                                                                                                                           | Story                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Color Palette (see note below) | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/src/blocks/components/ColorPalette.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-colorpalette--page) |
| Icon                           | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/icon/icon.tsx)       | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels)       |
| Typography                     | [See implementation](https://github.com/storybookjs/storybook/tree/next/code/core/src/components/components/typography)          | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all)    |

The color palette implemented by `@storybook/addon-docs/blocks` is a high-level abstraction of the [`storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/core/src/theming) module.

## Build system

When you're developing your addon as a package, you can’t use `npm link` to add it to your project. List your addon as a local dependency into your package.json:

```json title="package.json"
{
  "dependencies": {
    "@storybook/addon-controls": "file:///home/username/myrepo"
  }
}
```

Run either `yarn` or `npm install` to install the addon.

## Hot module replacement

While developing your addon, you can configure HMR (hot module replacement) to reflect the changes made.

## Standalone Storybook addons

If you're developing a standalone addon, add a new script to `package.json` with the following:

```json title="package.json"
{
  "scripts": {
    "start": "npm run build -- --watch"
  }
}
```

### Local Storybook addons

If you're developing a local Storybook addon built on top of an existing Storybook installation, HMR (hot module replacement) is available out of the box.

## Composing addons in presets

If you're working on a preset that loads third-party addons, which you don't have control over, and you need access to certain features (e.g., decorators) or provide additional configurations. In that case, you'll need to update your preset to the following to allow you to load and configure the other addons:

```js
// my-preset/index.js
function managerEntries(entry = []) {
  return [...entry, import.meta.resolve('my-other-addon/manager')];
}

const previewAnnotations = (entry = [], options) => {
  return [...entry, import.meta.resolve('my-other-addon/preview')];
};

export default {
  managerEntries,
  previewAnnotations,
};
```

If you have control over the addons you want to customize. In that case, you can update your preset and implement a custom function to load any additional presets and provide the necessary configuration.
> Source: https://storybook.js.org/docs/addons/addon-knowledge-base
---

# Addon API

Storybook's API allows developers to interact programmatically with Storybook. With the API, developers can build and deploy custom addons and other tools that enhance Storybook's functionality.

## Core Addon API

Our API is exposed via two distinct packages, each one with a different purpose:

- `storybook/manager-api` used to interact with the Storybook manager UI or access the Storybook API.
- `storybook/preview-api` used to control and configure the addon's behavior.

```js
// my-addon/src/manager.js|ts

```

### addons.add()

The `add` method allows you to register the type of UI component associated with the addon (e.g., panels, toolbars, tabs). For a minimum viable Storybook addon, you should provide the following arguments:

- `type`: The type of UI component to register.
- `title`: The title to feature in the Addon Panel.
- `render`: The function that renders the addon's UI component.

```js
// my-addon/src/manager.js|ts

const ADDON_ID = 'myaddon';
const PANEL_ID = `${ADDON_ID}/panel`;

addons.register(ADDON_ID, (api) => {
  addons.add(PANEL_ID, {
    type: types.PANEL,
    title: 'My Addon',
    render: ({ active }) => (
      
        <div> Storybook addon panel </div>
      
    ),
  });
});
```

The render function is called with `active`. The `active` value will be true when the panel is focused on the UI.

### addons.register()

Serves as the entry point for all addons. It allows you to register an addon and access the Storybook [API](#storybook-api). For example:

```js
// my-addon/src/manager.js|ts

// Register the addon with a unique name.
addons.register('my-organisation/my-addon', (api) => {});
```

Now you'll get an instance to our StorybookAPI. See the [api docs](#storybook-api) for Storybook API regarding using that.

### addons.getChannel()

Get an instance to the channel to communicate with the manager and the preview. You can find this in both the addon register code and your addon’s wrapper component (where used inside a story).

It has a NodeJS [EventEmitter](https://nodejs.org/api/events.html) compatible API. So, you can use it to emit events and listen to events.

```js
// my-addon/src/manager.js|ts

const ExampleToolbar = () => {
  const [globals, updateGlobals] = useGlobals();

  const isActive = globals['my-param-key'] || false;

  // Function that will update the global value and trigger a UI refresh.
  const refreshAndUpdateGlobal = () => {
    updateGlobals({
      ['my-param-key']: !isActive,
    });
    // Invokes Storybook's addon API method (with the FORCE_RE_RENDER) event to trigger a UI refresh
    addons.getChannel().emit(FORCE_RE_RENDER);
  };

  const toggleToolbarAddon = useCallback(() => refreshAndUpdateGlobal(), [isActive]);

  return (
    
      
    
  );
};
```

### makeDecorator

Use the `makeDecorator` API to create decorators in the style of the official addons. Like so:

```js
// my-addon/src/decorator.js|ts

export const withAddonDecorator = makeDecorator({
  name: 'withSomething',
  parameterName: 'CustomParameter',
  skipIfNoParametersOrOptions: true,
  wrapper: (getStory, context, { parameters }) => {
    /*
     * Write your custom logic here based on the parameters passed in Storybook's stories.
     * Although not advised, you can also alter the story output based on the parameters.
     */
    return getStory(context);
  },
});
```

If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called.

The `makeDecorator` API requires the following arguments:

- `name`: Unique name to identify the custom addon decorator.
- `parameterName`: Sets a unique parameter to be consumed by the addon.
- `skipIfNoParametersOrOptions`: (Optional) Doesn't run the decorator if the user hasn't options either via [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) or [parameters](https://storybook.js.org/docs/writing-stories/parameters.md).
- `wrapper`: your decorator function. Takes the `getStory`, `context`, and both the `options` and `parameters` (as defined in `skipIfNoParametersOrOptions` above).

---

## Storybook API

Storybook's API allows you to access different functionalities of Storybook UI.

### api.selectStory()

The `selectStory` API method allows you to select a single story. It accepts the following two parameters; story kind name and an optional story name. For example:

```tsx
// Button.stories.ts|tsx — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
  //👇 Creates specific parameters for the story
  parameters: {
    myAddon: {
      data: 'This data is passed to the addon',
    },
  },
} satisfies Meta<typeof Button>;

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

/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.js.org/docs/api/csf
 * to learn how to use render functions.
 */
export const Basic: Story = {
  render: () => Hello,
};
```

```tsx
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
  //👇 Creates specific parameters for the story
  parameters: {
    myAddon: {
      data: 'This data is passed to the addon',
    },
  },
});

/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.js.org/docs/api/csf
 * to learn how to use render functions.
 */
export const Basic = meta.story({
  render: () => Hello,
});
```

This is how you can select the above story:

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  api.selectStory('Button', 'Default');
});
```

### api.selectInCurrentKind()

Similar to the `selectStory` API method, but it only accepts the story as the only parameter.

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  api.selectInCurrentKind('Default');
});
```

### api.setQueryParams()

This method allows you to set query string parameters. You can use that as temporary storage for addons. Here's how you define query params:

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  api.setQueryParams({
    exampleParameter: 'Sets the example parameter value',
    anotherParameter: 'Sets the another parameter value',
  });
});
```

Additionally, if you need to remove a query parameter, set it as `null` instead of removing them from the addon. For example:

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  api.setQueryParams({
    exampleParameter: null,
  });
});
```

### api.getQueryParam()

Allows retrieval of a query parameter enabled via the `setQueryParams` API method. For example:

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  api.getQueryParam('exampleParameter');
});
```

### api.getUrlState(overrideParams)

This method allows you to get the application URL state, including any overridden or custom parameter values. For example:

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  const href = api.getUrlState({
    selectedKind: 'kind',
    selectedStory: 'story',
  }).url;
});
```

### api.getStoryHrefs(storyId, options?)

Get the manager and preview URLs for a story. URLs are relative to the current Storybook, unless `base` is set, or in case of previewHref with `refId` set.

- `storyId` (required): The ID of the story to get the URLs for
- `options` (optional):
  - `base`: Return an absolute href based on the current origin or network address.
  - `inheritArgs`: Inherit args from the current URL. If `storyId` matches current story, `inheritArgs` defaults to true.
  - `inheritGlobals`: Inherit globals from the current URL. Defaults to true.
  - `queryParams`: Additional query params to append to the URL (`args` and `globals` are merged when inheriting).
  - `refId`: ID of the ref to get the URL for (for composed Storybooks)
  - `viewMode`: The view mode to use, defaults to 'story'.

```js
addons.register('my-organisation/my-addon', (api) => {
  // Get the manager and preview URLs for a story
  const { managerHref, previewHref } = api.getStoryHrefs('button--primary');

  // Get absolute URLs based on the current manager URL (origin)
  api.getStoryHrefs('button--primary', { base: 'origin' });

  // Get absolute URLs based on the dev server's local network IP address
  api.getStoryHrefs('button--primary', { base: 'network' });

  // Get clean URLs without args or globals
  api.getStoryHrefs('button--primary', { inheritArgs: false, inheritGlobals: false });

  // With args and globals (merged on top of inherited args/globals) as well as a custom query param
  // Note that args and globals should be serialized (see `buildArgsParam` from `storybook/internal/router`)
  api.getStoryHrefs('button--primary', {
    queryParams: { args: 'label:Label', globals: 'outline:!true', custom: 'value' },
  });

  // Link to a story from an external ref
  api.getStoryHrefs('button--primary', { refId: 'external-ref' });

  // Link to a docs page
  api.getStoryHrefs('button--docs', { viewMode: 'docs' });
});
```

### api.on(eventName, fn)

This method allows you to register a handler function called whenever the user navigates between stories.

```js
// my-addon/src/manager.js|ts
addons.register('my-organisation/my-addon', (api) => {
  // Logs the event data to the browser console whenever the event is emitted.
  api.on('custom-addon-event', (eventData) => console.log(eventData));
});
```

### api.openInEditor(payload)

Opens a file in the configured code editor. Useful for "Edit in IDE" functionality in addons.

- `payload.file`: The file path to open (required)
- `payload.line`: Optional line number to jump to
- `payload.column`: Optional column number to jump to

Returns a Promise that resolves with information about whether the operation was successful.

```js
addons.register('my-organisation/my-addon', (api) => {
  // Open a file in the editor
  api.openInEditor({
    file: './src/components/Button.tsx',
  });

  // Handle the api response
  api
    .openInEditor({
      file: './src/components/Button.tsx',
      line: 42,
      column: 15,
    })
    .then((response) => {
      if (response.error) {
        console.error('Failed to open file:', response.error);
      } else {
        console.log('File opened successfully');
      }
    });
});
```

### api.getCurrentStoryData()

Returns the current story's data, including its ID, kind, name, and parameters.

```js
addons.register('my-organisation/my-addon', (api) => {
  // Get data about the currently selected story
  const storyData = api.getCurrentStoryData();
  console.log('Current story:', storyData.id, storyData.title);
});
```

### api.toggleFullscreen(toggled?)

Toggles the fullscreen mode of the Storybook UI. Pass `true` to enable fullscreen, `false` to disable, or omit to toggle the current state.

```js
addons.register('my-organisation/my-addon', (api) => {
  // Toggle fullscreen mode
  api.toggleFullscreen();

  // Enable fullscreen
  api.toggleFullscreen(true);

  // Disable fullscreen
  api.toggleFullscreen(false);
});
```

### api.togglePanel(toggled?)

Toggles the visibility of the addon panel. Pass `true` to show the panel, `false` to hide, or omit to toggle the current state.

```js
addons.register('my-organisation/my-addon', (api) => {
  // Toggle panel visibility
  api.togglePanel();

  // Show the panel
  api.togglePanel(true);

  // Hide the panel
  api.togglePanel(false);
});
```

### api.addNotification(notification)

Displays a notification in the Storybook UI. The notification object should contain `id`, `content`, and optionally `duration` and `icon`.

```js

addons.register('my-organisation/my-addon', (api) => {
  // Add a simple notification
  api.addNotification({
    id: 'my-notification',
    content: {
      headline: 'Action completed',
      subHeadline: 'Your changes have been saved successfully',
    },
    duration: 5000, // 5 seconds
  });

  // Add a notification with an icon
  api.addNotification({
    id: 'success-notification',
    content: {
      headline: 'Success!',
      subHeadline: 'Operation completed successfully',
    },
    icon: ,
    duration: 3000,
  });
});
```

### addons.setConfig(config)

This method allows you to override the default Storybook UI configuration (e.g., set up a [theme](https://storybook.js.org/docs/configure/user-interface/theming.md) or hide UI elements):

```ts
// .storybook/manager.ts

addons.setConfig({
  navSize: 300,
  bottomPanelHeight: 300,
  rightPanelWidth: 300,
  panelPosition: 'bottom',
  enableShortcuts: true,
  showToolbar: true,
  theme: undefined,
  selectedPanel: undefined,
  initialActive: 'sidebar',
  layoutCustomisations: {
    showSidebar(state: State, defaultValue: boolean) {
      return state.storyId === 'landing' ? false : defaultValue;
    },
    showToolbar(state: State, defaultValue: boolean) {
      return state.viewMode === 'docs' ? false : defaultValue;
    },
  },
  sidebar: {
    showRoots: false,
    collapsedRoots: ['other'],
  },
  toolbar: {
    title: { hidden: false },
    zoom: { hidden: false },
    eject: { hidden: false },
    copy: { hidden: false },
    fullscreen: { hidden: false },
  },
});
```

The following table details how to use the API values:

| Name                  | Type            | Description                                             | Example Value                       |
| --------------------- | --------------- | ------------------------------------------------------- | ----------------------------------- |
| **navSize**           | Number (pixels) | The size of the sidebar that shows a list of stories    | `300`                               |
| **bottomPanelHeight** | Number (pixels) | The size of the addon panel when in the bottom position | `200`                               |
| **rightPanelWidth**   | Number (pixels) | The size of the addon panel when in the right position  | `200`                               |
| **panelPosition**     | String          | Where to show the addon panel                           | `'bottom'` or `'right'`             |
| **enableShortcuts**   | Boolean         | Enable/disable shortcuts                                | `true`                              |
| **showToolbar**       | Boolean         | Show/hide toolbar                                       | `true`                              |
| **theme**             | Object          | Storybook Theme, see next section                       | `undefined`                         |
| **selectedPanel**     | String          | Id to select an addon panel                             | `storybook/actions/panel`           |
| **initialActive**     | String          | Select the default active tab on Mobile                 | `sidebar` or `canvas` or `addons`   |
| **sidebar**           | Object          | Sidebar options, see below                              | `{ showRoots: false }`              |
| **toolbar**           | Object          | Modify the tools in the toolbar using the addon id      | `{ fullscreen: { hidden: false } }` |

The following options are configurable under the `sidebar` namespace:

| Name               | Type     | Description                                                   | Example Value                                         |
| ------------------ | -------- | ------------------------------------------------------------- | ----------------------------------------------------- |
| **showRoots**      | Boolean  | Display the top-level nodes as a "root" in the sidebar        | `false`                                               |
| **collapsedRoots** | Array    | Set of root node IDs to visually collapse by default          | `['misc', 'other']`                                   |
| **renderLabel**    | Function | Create a custom label for tree nodes; must return a ReactNode | `(item, api) => <abbr title="...">{item.name}</abbr>` |

The following options are configurable under the `toolbar` namespace:

| Name     | Type   | Description                                                          | Example Value       |
| -------- | ------ | -------------------------------------------------------------------- | ------------------- |
| **[id]** | String | Toggle visibility for a specific toolbar item (e.g. `title`, `zoom`) | `{ hidden: false }` |

---

## Storybook hooks

To help streamline addon development and reduce boilerplate code, the API exposes a set of hooks to access Storybook's internals. These hooks are an extension of the `storybook/manager-api` module.

### useStorybookState

It allows access to Storybook's internal state. Similar to the [`useglobals`](#useglobals) hook, we recommend optimizing your addon to rely on [`React.memo`](https://react.dev/reference/react/memo), or the following hooks; [`useMemo`](https://react.dev/reference/react/useMemo), [`useCallback`](https://react.dev/reference/react/useCallback) to prevent a high volume of re-render cycles.

```js
// my-addon/src/manager.js|ts

export const Panel = () => {
  const state = useStorybookState();
  return (
    
      {state.viewMode !== 'docs' ? (
        <h2>Do something with the documentation</h2>
      ) : (
        <h2>Show the panel when viewing the story</h2>
      )}
    
  );
};
```

### useStorybookApi

The `useStorybookApi` hook is a convenient helper to allow you full access to the [Storybook API](#storybook-api) methods.

```js
// my-addon/manager.js|ts

export const Panel = () => {
  const [globals, updateGlobals] = useGlobals();
  const api = useStorybookApi();

  const isActive = [true, 'true'].includes(globals[PARAM_KEY]);

  const toggleMyTool = useCallback(() => {
    updateGlobals({
      [PARAM_KEY]: !isActive,
    });
  }, [isActive]);

  useEffect(() => {
    api.setAddonShortcut('custom-toolbar-addon', {
      label: 'Enable my addon',
      defaultShortcut: ['G'],
      actionName: 'Toggle',
      showInMenu: false,
      action: toggleMyTool,
    });
  }, [api]);

  return (
    
      
    
  );
};
```

### useChannel

Allows setting subscriptions to events and getting the emitter to emit custom events to the channel.

The messages can be listened to on both the iframe and the manager.

```js
// my-addon/manager.js|ts

export const Panel = () => {
  // Creates a Storybook API channel and subscribes to the STORY_CHANGED event
  const emit = useChannel({
    STORY_CHANGED: (...args) => console.log(...args),
  });

  return (
    
       emit('my-event-type', { sampleData: 'example' })}>
        Emit a Storybook API event with custom data
      
    
  );
};
```

### useAddonState

The `useAddonState` is a useful hook for addons that require data persistence, either due to Storybook's UI lifecycle or for more complex addons involving multiple types (e.g., toolbars, panels).

```js
// my-addon/manager.js|ts

export const Panel = () => {
  const [state, setState] = useAddonState('addon-unique-identifier', 'initial state');

  return (
    
       setState('Example')}>
        Click to update Storybook's internal state
      
    
  );
};
export const Tool = () => {
  const [state, setState] = useAddonState('addon-unique-identifier', 'initial state');

  return (
     setState('Example')}
    >
      
    
  );
};
```

### useParameter

The `useParameter` retrieves the current story's parameters. If the parameter's value is not defined, it will automatically default to the second value defined.

```js
// my-addon/manager.js|ts

export const Panel = () => {
  // Connects to Storybook's API and retrieves the value of the custom parameter for the current story
  const value = useParameter('custom-parameter', 'initial value');

  return (
    
      {value === 'initial value' ? (
        <h2>The story doesn't contain custom parameters. Defaulting to the initial value.</h2>
      ) : (
        <h2>You've set {value} as the parameter.</h2>
      )}
    
  );
};
```

### useGlobals

Extremely useful hook for addons that rely on Storybook [Globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md). It allows you to obtain and update `global` values. We also recommend optimizing your addon to rely on [`React.memo`](https://react.dev/reference/react/memo), or the following hooks; [`useMemo`](https://react.dev/reference/react/useMemo), [`useCallback`](https://react.dev/reference/react/useCallback) to prevent a high volume of re-render cycles.

```js
// my-addon/manager.js|ts

export const Panel = () => {
  const [globals, updateGlobals] = useGlobals();

  const isActive = globals['my-param-key'] || false; // 👈 Sets visibility based on the global value.

  return (
    
       updateGlobals({ ['my-param-key']: !isActive })}>
        {isActive ? 'Hide the addon panel' : 'Show the panel'}
      
    
  );
};
```

### useArgs

Hook that allows you to retrieve or update a story's [`args`](https://storybook.js.org/docs/writing-stories/args.md).

```js
// my-addon/src/manager.js|ts

const [args, updateArgs, resetArgs] = useArgs();

// To update one or more args:
updateArgs({ key: 'value' });

// To reset one (or more) args:
resetArgs((argNames: ['key']));

// To reset all args
resetArgs();
```

**Learn more about the Storybook addon ecosystem**

- [Types of addons](https://storybook.js.org/docs/addons/addon-types.md) for other types of addons
- [Writing addons](https://storybook.js.org/docs/addons/writing-addons.md) for the basics of addon development
- [Presets](https://storybook.js.org/docs/addons/writing-presets.md) for preset development
- [Integration catalog](https://storybook.js.org/docs/addons/integration-catalog.md) for requirements and available recipes
- API reference to learn about the available APIs
> Source: https://storybook.js.org/docs/addons/addons-api
---

# Addon migration guide for Storybook 10.0

We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 10.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 9.x to 10.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 9.0](https://storybook.js.org/docs/9/addons/addon-migration-guide.md).

We also have a general [Storybook migration guide](https://storybook.js.org/docs/releases/migration-guide.md) that covers updates to your Storybook instance rather than your addon code.

## Dependency updates

You will need to update your Storybook dependencies. Peer dependencies must point to `^10.0.0` to ensure broad compatibility for your end users. Development dependencies can be set to `^10.0.0`, or to `next` if you want to try the latest prerelease all year round.

```jsonc title="package.json"
{
  "devDependencies": {
    "@storybook/addon-docs": "next",
    "@storybook/react-vite": "next",
    "storybook": "next",
  },
  "peerDependencies": {
    "storybook": "^10.0.0",
  },
}
```

If you still have `@storybook/addon-essentials`, `@storybook/addon-interactions`, `@storybook/addon-links`, or `@storybook/blocks` in your dependencies, you will need to remove them. These packages are empty since Storybook 9 and will no longer be published going forward.

### Supporting earlier versions

If your addon supports multiple major versions of Storybook, you can specify a wider version range in your peer dependencies:

```jsonc title="package.json"
{
  "name": "your-storybook-addon",
  "peerDependencies": {
    "storybook": "^9.0.0 || ^10.0.0",
  },
  "devDependencies": {
    "storybook": ">=10.0.0-0 <11.0.0-0", // For local development
  },
}
```

However, we recommend releasing a new major version of your addon alongside new major versions of Storybook. This practice:

1. Makes it easier to maintain your code
2. Allows you to take advantage of new features and improvements
3. Provides a clearer upgrade path for your users

## Key changes for addons

Here are the changes in version 10.0 that impact addon development.

### ESM-only builds

Storybook 10 requires all addons to be built as ESM-only. This change simplifies the build process and reduces maintenance overhead. You'll need to make many changes to `tsup.config.ts`, so it can be easier to copy the reference file in the [`addon-kit` repository](https://github.com/storybookjs/addon-kit/blob/main/tsup.config.ts).

This update brings the following changes:

- The Node target moves from Node 20.0 to Node 20.19
- You no longer need to build CJS files
- You no longer need to pass `globalManagerPackages` and `globalPreviewPackages`
- The `bundler` config in `package.json` no longer needs to be manually typed
- We recommend you stop using `exportEntries` and switch exported entries to `previewEntries` and `managerEntries` instead based on where they are consumed by your users

```diff title="tsup.config.ts"
- import { readFile } from "node:fs/promises";

- import { globalPackages as globalManagerPackages } from "storybook/internal/manager/globals";
- import { globalPackages as globalPreviewPackages } from "storybook/internal/preview/globals";

- const NODE_TARGET: Options["target"] = "node20";
+ const NODE_TARGET = "node20.19"; // Minimum Node version supported by Storybook 10

- type BundlerConfig = {
-   bundler?: {
-     exportEntries?: string[];
-     nodeEntries?: string[];
-     managerEntries?: string[];
-     previewEntries?: string[];
-   };
- };

export default defineConfig(async (options) => {
  // reading the three types of entries from package.json, which has the following structure:
  // {
  //  ...
  //   "bundler": {
-  //     "exportEntries": ["./src/index.ts"],
  //     "managerEntries": ["./src/manager.ts"],
-  //     "previewEntries": ["./src/preview.ts"],
+  //     "previewEntries": ["./src/preview.ts", "./src/index.ts"],
  //     "nodeEntries": ["./src/preset.ts"]
  //   }
  // }
-   const packageJson = (await readFile("./package.json", "utf8").then(
-     JSON.parse,
-   )) as BundlerConfig;
+   const packageJson = (
+     await import("./package.json", { with: { type: "json" } })
+   ).default;
+
  const {
    bundler: {
-      exportEntries = [],
      managerEntries = [],
      previewEntries = [],
      nodeEntries = [],
-    } = {},
+    },
  } = packageJson;

  const commonConfig: Options = {
-    splitting: false,
+    splitting: true,
+    format: ["esm"],
-    minify: !options.watch,
    treeshake: true,
-    sourcemap: true,
    // keep this line commented until https://github.com/egoist/tsup/issues/1270 is resolved
    // clean: options.watch ? false : true,
    clean: false,
+    // The following packages are provided by Storybook and should always be externalized
+    // Meaning they shouldn't be bundled with the addon, and they shouldn't be regular dependencies either
+    external: ["react", "react-dom", "@storybook/icons"],
  };

  const configs: Options[] = [];
-
-   // export entries are entries meant to be manually imported by the user
-   // they are not meant to be loaded by the manager or preview
-   // they'll be usable in both node and browser environments, depending on which features and modules they depend on
-   if (exportEntries.length) {
-     configs.push({
-       ...commonConfig,
-       entry: exportEntries,
-       dts: {
-         resolve: true,
-       },
-       format: ["esm", "cjs"],
-       platform: "neutral",
-       target: NODE_TARGET,
-       external: [...globalManagerPackages, ...globalPreviewPackages],
-     });
-   }

  // manager entries are entries meant to be loaded into the manager UI
  // they'll have manager-specific packages externalized and they won't be usable in node
  // they won't have types generated for them as they're usually loaded automatically by Storybook
  if (managerEntries.length) {
    configs.push({
      ...commonConfig,
      entry: managerEntries,
-      format: ["esm"],
      platform: "browser",
-      target: BROWSER_TARGETS,
+      target: "esnext", // we can use esnext for manager entries since Storybook will bundle the addon's manager entries again anyway
-      external: globalManagerPackages,
    });
  }

  // preview entries are entries meant to be loaded into the preview iframe
  // they'll have preview-specific packages externalized and they won't be usable in node
  // they'll have types generated for them so they can be imported when setting up Portable Stories
  if (previewEntries.length) {
    configs.push({
      ...commonConfig,
      entry: previewEntries,
-      dts: {
-        resolve: true,
-      },
-      format: ["esm", "cjs"],
      platform: "browser",
-      target: BROWSER_TARGETS,
+      target: "esnext", // we can use esnext for preview entries since Storybook will bundle the addon's preview entries again anyway
-      external: globalPreviewPackages,
+      dts: true,
    });
  }

  // node entries are entries meant to be used in node-only
  // this is useful for presets, which are loaded by Storybook when setting up configurations
  // they won't have types generated for them as they're usually loaded automatically by Storybook
  if (nodeEntries.length) {
    configs.push({
      ...commonConfig,
      entry: nodeEntries,
-      format: ["cjs"],
      platform: "node",
      target: NODE_TARGET,
    });
```

Next, update the `exports` field in your `package.json` to remove mentions of CJS files.

```diff title="package.json"
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
    },
    "./preview": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/preview.js",
-      "require": "./dist/preview.cjs"
+      "types": "./dist/preview.d.ts",
+      "default": "./dist/preview.js"
    },
-    "./preset": "./dist/preset.cjs",
+    "./preset": "./dist/preset.js",
    "./manager": "./dist/manager.js",
    "./package.json": "./package.json"
  },
```

Update `tsconfig.json`.

```diff title="tsconfig.json"
{
  "compilerOptions": {
    // …
+    "moduleResolution": "bundler",
    // …
-    "module": "commonjs",
+    "module": "preserve",
    // …
-    "target": "ES2020",
+    "target": "esnext",
    // …
-    "lib": ["es2020", "dom", "dom.iterable"],
+    "lib": ["esnext", "dom", "dom.iterable"],
    // …
-    "rootDir": "./src",
+    "rootDir": ".",
  },
-  "include": ["src/**/*"]
+  "include": ["src/**/*", "tsup.config.ts"]
 }
```

Finally, change the `preset.js` file at the top-level of your addon to be ESM. This file used to be CJS because the Storybook Node app only supported CJS.

```diff title="preset.js"
-// this file is slightly misleading. It needs to be CJS, and thus in this "type": "module" package it should be named preset.cjs
-// but Storybook won't pick that filename up so we have to name it preset.js instead
-
-module.exports = require('./dist/preset.cjs');
+export * from './dist/preset.js';
```

### Local addon loading

Because addons are now ESM-only, you must change how you load your own addon in your development Storybook instance. Imports and exports must now follow ESM syntax, and relative paths must use `import.meta.resolve`.

Remove `.storybook/local-preset.cjs` and create `.storybook/local-preset.ts` with the following content:

```ts title=".storybook/local-preset.ts"

export function previewAnnotations(entry = []) {
  return [...entry, fileURLToPath(import.meta.resolve('../dist/preview.js'))];
}

export function managerEntries(entry = []) {
  return [...entry, fileURLToPath(import.meta.resolve('../dist/manager.js'))];
}

export * from '../dist/preset.js';
```

Next, update your `main.ts` to reference the new preset file:

```diff title=".storybook/main.ts"
- addons: ["@storybook/addon-docs", "./local-preset.cjs"],
+ addons: ["@storybook/addon-docs", import.meta.resolve("./local-preset.ts")],
```

## Optional changes

The following changes are not strictly required yet, but we recommend making them to improve your users' experience.

### CSF Factories support

To support CSF Factories annotations in your addon, you will need to update your `src/index.ts` file to use the new `definePreviewAddon`. This feature will be part of [CSF Next](https://storybook.js.org/docs/api/csf/csf-next.md). This change is highly recommended, as it will help your own users reap the benefits of CSF Factories.

With CSF Factories, users can chain their preview configuration and benefit from better typing and more flexibility. Addons must export annotations to be compatible with this new syntax. CSF Factories will be the default way to write stories in Storybook 11.

```diff title="src/index.ts"
- // make it work with --isolatedModules
- export default {};
+ import { definePreviewAddon } from "storybook/internal/csf";
+ import addonAnnotations from "./preview";
+
+ export default () => definePreviewAddon(addonAnnotations);
```

### Removal of exportEntries

The `exportEntries` property in `package.json`'s `bundler` was used to produce the `index.js` build output from `src/index.ts`. It was compatible with Node.js, rather than strictly with browsers. This build configuration could cause subtle bugs when addon authors exported code in `index.js` for use in the Storybook preview or manager.

In the Storybook 10 [addon-kit](https://github.com/storybookjs/addon-kit), we removed `exportEntries` from the `bundler` config, and we moved `src/index.ts` to be part of `previewEntries` instead. This way, any code exported from `src/index.ts` is bundled for browsers and usable with CSF Next. If you need to export additional code to run in the preview (such as optional decorators), you can add them to `src/index.ts`.

If you need to export code for the manager (such as a `renderLabel` function for the sidebar), you can create a new `src/manager-helpers.ts` file and add it to `managerEntries`, like so:

```diff title="package.json"
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./preview": {
      "types": "./dist/preview.d.ts",
      "default": "./dist/preview.js"
    },
    "./preset": "./dist/preset.js",
    "./manager": "./dist/manager.js",
+    "./manager-helpers": "./dist/manager-helpers.js",
    "./package.json": "./package.json"
  },
  "bundler": {
    "managerEntries": [
+      "src/manager-helpers.ts",
      "src/manager.tsx"
    ]
  }
```

### Build file cleanup

We recommend removing your old build files as you build. This will avoid your `dist` folder growing with expired JS chunks. You may add the following to your `package.json` scripts:

```diff title="package.json"
{
  "scripts": {
+    "prebuild": "node -e \"fs.rmSync('./dist', { recursive: true, force: true })\"",
  }
}
```

### Package keyword changes

We've updated default keywords for addons in the Storybook `addon-kit` template.

```diff title="package.json"
  "keywords": [
-    "storybook-addons",
+    "storybook-addon",
  ],
```

## 10.0.0 full migration guide

For a full list of changes, please visit the [Migration.md](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-9x-to-1000) file

## Migration example

For a complete example of an addon updated to support Storybook 10.0, refer to the [Addon Kit migration PR](https://github.com/storybookjs/addon-kit/pull/82).
Once merged, it will demonstrate all the necessary and recommended changes for Storybook 10.

## Releasing

To support Storybook 10.0, we encourage you to release a new major version of your addon. For experimental features or testing, use the `next` tag. This allows you to gather feedback before releasing a stable version.

## Support

If you're having issues with your addon after following this guide, please open a [new discussion](https://github.com/storybookjs/storybook/discussions/new?category=migrations) in our GitHub repository or come talk to us in our [dedicated addon developer channel, `#addons`](https://discord.gg/KKXFQy9sFc) on Discord.
> Source: https://storybook.js.org/docs/addons/addon-migration-guide
---

# Configure Storybook

Storybook is configured via a folder called `.storybook`, which contains various configuration files.

Note that you can change the folder that Storybook uses by setting the `-c` flag to your `storybook dev` and `storybook build` [CLI commands](https://storybook.js.org/docs/api/cli-options.md).

## Configure your Storybook project

Storybook's main configuration (i.e., the `main.js|ts`) defines your Storybook project's behavior, including the location of your stories, the addons you use, feature flags and other project-specific settings. This file should be in the `.storybook` folder in your project's root directory. You can author this file in either JavaScript or [TypeScript](https://storybook.js.org/docs/configure/integration/typescript.md). Listed below are the available options and examples of how to use them.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-docs'],
  staticDirs: ['../public'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-docs'],
  staticDirs: ['../public'],
});
```

This configuration file is a [preset](https://storybook.js.org/docs/addons/addon-types.md) and, as such, has a powerful interface, which can be further customized. Read our documentation on writing [presets](https://storybook.js.org/docs/addons/writing-presets.md) to learn more.

| Configuration element | Description                                                                                                                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stories`             | The array of globs that indicates the [location of your story files](#configure-story-loading), relative to `main.js`                                                                                                             |
| `staticDirs`          | Sets a list of directories of [static files](https://storybook.js.org/docs/configure/integration/images-and-assets.md#serving-static-files-via-storybook-configuration) to be loaded by Storybook <br /> `staticDirs: ['../public']`                                   |
| `addons`              | Sets the list of [addons](https://storybook.js.org/integrations) loaded by Storybook <br /> `addons: ['@storybook/addon-docs']`                                                                                                   |
| `typescript`          | Configures how Storybook handles [TypeScript files](https://storybook.js.org/docs/configure/integration/typescript.md) <br /> `typescript: { check: false, checkOptions: {} }`                                                                                         |
| `framework`           | Configures Storybook based on a set of [framework-specific](https://storybook.js.org/docs/configure/integration/frameworks.md) settings <br /> `framework: { name: '@storybook/svelte-vite', options:{} }`                                                             |
| `core`                | Configures Storybook's [internal features](https://storybook.js.org/docs/api/main-config/main-config-core.md) <br /> `core: { disableTelemetry: true, }`                                                                                                    |
| `docs`                | Configures Storybook's [auto-generated documentation](https://storybook.js.org/docs/writing-docs/autodocs.md)<br /> `docs: { defaultName: 'Documentation' }`                                                                                                |
| `features`            | Enables Storybook's [additional features](https://storybook.js.org/docs/api/main-config/main-config-features.md)<br /> See table below for a list of available features                                                                                     |
| `refs`                | Configures [Storybook composition](https://storybook.js.org/docs/sharing/storybook-composition.md) <br /> `refs: { example: { title: 'ExampleStorybook', url:'https://your-url.com' } }`                                                                    |
| `logLevel`            | Configures Storybook's logs in the browser terminal. Useful for debugging <br /> `logLevel: 'debug'`                                                                                                                              |
| `webpackFinal`        | Customize Storybook's [Webpack](https://storybook.js.org/docs/builders/webpack.md) setup <br /> `webpackFinal: async (config:any) => { return config; }`                                                                                                    |
| `viteFinal`           | Customize Storybook's Vite setup when using the [vite builder](https://github.com/storybookjs/builder-vite) <br /> `viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }`                         |
| `env`                 | Defines custom Storybook [environment variables](https://storybook.js.org/docs/configure/environment-variables.md#using-storybook-configuration). <br /> `env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),`                                                |
| `build`               | Optimizes Storybook's production [build](https://storybook.js.org/docs/api/main-config/main-config-build.md) for performance by excluding specific features from the bundle. Useful when decreased build times are a priority. <br /> `build: { test: {} }` |

## Configure story loading

By default, Storybook will load stories from your project based on a glob (pattern matching string) in `.storybook/main.js|ts` that matches all files in your project with extension `.stories.*`. The intention is for you to colocate a story file along with the component it documents.

```
•
└── components
    ├── Button.js
    └── Button.stories.js
```

If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features).

For example, if you wanted to pull both `.md` and `.js` files from the `my-project/src/components` directory, you could write:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../my-project/src/components/*.@(js|md)'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../my-project/src/components/*.@(js|md)'],
});
```

### With a configuration object

Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. For example, if you wanted to load your stories from a `packages/components` directory, you could adjust your `stories` configuration field into the following:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../packages/components',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
      // 👇 Used when generating automatic titles for your stories
      titlePrefix: 'MyComponents',
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../packages/components',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
      // 👇 Used when generating automatic titles for your stories
      titlePrefix: 'MyComponents',
    },
  ],
});
```

When Storybook starts, it will look for any file containing the `stories` extension inside the `packages/components` directory and generate the titles for your stories.

### With a directory

You can also simplify your Storybook configuration and load the stories using a directory. For example, if you want to load all the stories inside a `packages/MyStories`, you can adjust the configuration as such:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  // 👇 Storybook will load all existing stories within the MyStories folder
  stories: ['../packages/MyStories'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  // 👇 Storybook will load all existing stories within the MyStories folder
  stories: ['../packages/MyStories'],
});
```

### With a custom implementation

You can also adjust your Storybook configuration and implement custom logic to load your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve. In that case, you could adjust your configuration as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

async function findStories(): Promise<StoriesEntry[]> {
  // your custom logic returns a list of files
}

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: async (list: StoriesEntry[]) => [
    ...list,
    // 👇 Add your found stories to the existing list of story files
    ...(await findStories()),
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

async function findStories(): Promise<StoriesEntry[]> {
  // your custom logic returns a list of files
}

export default defineMain({
  framework: '@storybook/your-framework',
  stories: async (list: StoriesEntry[]) => [
    ...list,
    // 👇 Add your found stories to the existing list of story files
    ...(await findStories()),
  ],
});
```

#### Known limitations

Because of the way stories are currently indexed in Storybook, loading stories on demand has a couple of minor limitations at the moment:

- [CSF formats](https://storybook.js.org/docs/api/csf.md) from version 1 to version 3 are supported.
- Custom `storySort` functions are allowed based on a restricted API.

## Configure story rendering

To control the way stories are rendered and add global [decorators](https://storybook.js.org/docs/writing-stories/decorators.md#global-decorators) and [parameters](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters), create a `.storybook/preview.js` file. This is loaded in the Canvas UI, the “preview” iframe that renders your components in isolation. Use `preview.js` for global code (such as [CSS imports](https://storybook.js.org/docs/get-started/setup.md#render-component-styles) or JavaScript mocks) that applies to all stories.

The `preview.js` file can be an ES module and export the following keys:

- `decorators` - an array of global [decorators](https://storybook.js.org/docs/writing-stories/decorators.md#global-decorators)
- `parameters` - an object of global [parameters](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters)
- `globalTypes` - definition of [globalTypes](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#global-types-and-the-toolbar-annotation)

If you’re looking to change how to order your stories, read about [sorting stories](https://storybook.js.org/docs/writing-stories/naming-components-and-hierarchy.md#sorting-stories).

## Configure Storybook’s UI

To control the behavior of Storybook’s UI (the **“manager”**), you can create a `.storybook/manager.js` file.

This file does not have a specific API but is the place to set [UI options](https://storybook.js.org/docs/configure/user-interface/features-and-behavior.md) and to configure Storybook’s [theme](https://storybook.js.org/docs/configure/user-interface/theming.md).
> Source: https://storybook.js.org/docs/configure
---

# Styling and CSS

There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually, it is best to try and replicate what your application does with styling in Storybook’s configuration.

## CSS

Storybook supports importing CSS files in a few different ways. Storybook will inject these tags into the preview iframe where your components render, not the Storybook Manager UI. The best way to import CSS depends on your project's configuration and your preferences.

### Import bundled CSS (recommended)

All Storybooks are pre-configured to recognize imports for CSS files. To add global CSS for all your stories, import it in [`.storybook/preview.ts|tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering). These files will be subject to HMR, so you can see your changes without restarting your Storybook server.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {},
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {},
});
```

If your component files import their CSS files, this will work too. However, if you're using CSS processor tools like Sass or Postcss, you may need some more configuration.

### Include static CSS

If you have a global CSS file that you want to include in all your stories, you can import it in [`.storybook/preview-head.html`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-head).
However, these files will not be subject to HMR, so you'll need to restart your Storybook server to see your changes.

```html
// .storybook/preview-head.html

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap"
  rel="stylesheet"
/>

<link rel="stylesheet" href="path/to/your/styles.css" />
```

## CSS modules

### Vite

Vite comes with CSS modules support out-of-the-box. If you have customized the CSS modules configuration in your `vite.config.js` this will automatically be applied to your Storybook as well. Read more about [Vite's CSS modules support](https://vitejs.dev/guide/features.html#css-modules).

### Webpack

Storybook recreates your Next.js configuration, so you can use CSS modules in your stories without any extra configuration.

If you're using Webpack and want to use CSS modules, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools.

## PostCSS

### Vite

Vite comes with PostCSS support out-of-the-box. If you have customized the PostCSS configuration in your `vite.config.js` this will automatically be applied to your Storybook as well. Read more about [Vite's PostCSS support](https://vitejs.dev/guide/features.html#postcss).

### Webpack

Storybook recreates your Next.js configuration, so you can use PostCSS in your stories without any extra configuration.

If you're using Webpack and want to use PostCSS, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools.

## CSS pre-processors

### Vite

Vite comes with Sass, Less, and Stylus support out-of-the-box. Read more about [Vite's CSS Pre-processor support](https://vitejs.dev/guide/features.html#css-pre-processors).

### Webpack

Storybook recreates your Next.js configuration, so you can use Sass in your stories without any extra configuration.

If you're using Webpack and want to use Sass or Less, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. Or if you'd prefer, you can customize [Storybook's webpack configuration yourself](https://storybook.js.org/docs/builders/webpack.md#override-the-default-configuration) to include the appropriate loader(s).

## CSS-in-JS

CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), which can be accomplished with `@storybook/addon-themes`'s [`withThemeFromJSXProvider` decorator](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider).

## Adding webfonts

### `.storybook/preview-head.html`

If you need webfonts to be available, you may need to add some code to the [`.storybook/preview-head.html`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-head) file. We recommend including any assets with your Storybook if possible, in which case you likely want to configure the [static file location](https://storybook.js.org/docs/configure/integration/images-and-assets.md#serving-static-files-via-storybook-configuration).

### `.storybook/preview.ts|tsx`

If you're using something like [`fontsource`](https://fontsource.org/) for your fonts, you can import the needed css files in your [`.storybook/preview.ts|tsx`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) file.
> Source: https://storybook.js.org/docs/configure/styling-and-css
---

# Telemetry

Storybook collects completely anonymous data to help us improve user experience. Participation in this anonymous program is optional, and you may opt-out if you'd not like to share any information.

## Why is telemetry collected?

Hundreds of thousands of developers use Storybook daily to build, test, and document components. Storybook is framework agnostic and integrates with the front-end ecosystem:

- **JavaScript frameworks** such as [React](https://reactjs.org/), [Vue 3](https://vuejs.org/), [Svelte](https://svelte.dev/) and [Solid](https://www.solidjs.com/)
- **Libraries** such as [Styled-Components](https://styled-components.com/), [Tailwind](https://tailwindcss.com/), [Redux](https://redux.js.org/)
- **Design tools** such as [Figma](https://figma.com/), [Sketch](https://www.sketch.com/), [Zeplin](https://zeplin.io/) and [InVision](https://www.invisionapp.com/)
- **Workflow tools** such as [Notion](https://www.notion.so/product), [Confluence](https://www.atlassian.com/software/confluence), and [Jira](https://www.atlassian.com/software/jira)

In the past, our improvement process relied on manually gathering feedback. But with a growing userbase and the need to support a wide variety of integrations, we need a more accurate method for gauging Storybook usage and pain points.

These telemetry data help us (the maintainers) to prioritize the highest impact projects. That allows us to keep up with trends in the front-end ecosystem and verify that our community's hard work achieves the intended result.

## What is being collected?

We collect general usage details, including command invocation, Storybook version, addons, and the view layer.

Specifically, we track the following information in our telemetry events:

- Timestamp of the occurrence.
- Command invoked (e.g., `init`, `upgrade`, `dev`, `build`).
- Storybook unique identifier: One-way hash generated during Storybook installation process.
- One way hash of the IP address where the event occurred for spam detection.
- Story count.
- Storybook version.
- Storybook metadata:
  - Language (e.g., TypeScript, JavaScript).
  - Supported view layers (e.g., React, Vue 3, Angular, Svelte).
  - Builder (e.g., Webpack5, Vite).
  - Meta framework (e.g., [Next](https://nextjs.org/), [Gatsby](https://www.gatsbyjs.com/), [CRA](https://create-react-app.dev/)).
  - [Addons](https://storybook.js.org/integrations) (e.g., [Accessibility](https://storybook.js.org/addons/@storybook/addon-a11y/)).
  - Testing tools (e.g. [Jest](https://jestjs.io/), [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/)).
- Package manager information (e.g., `npm`, `yarn`).
- Monorepo information (e.g., [NX](https://nx.dev/), [Turborepo](https://turborepo.org/)).
- In-app events (e.g., [Storybook guided tour](https://github.com/storybookjs/addon-onboarding), [UI test run](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#storybook-ui)).

Access to the raw data is highly controlled, limited to select members of Storybook's core team who maintain the telemetry. We cannot identify individual users from the dataset: it is anonymized and untraceable back to the user.

## What about sensitive information?

We take your privacy and our security very seriously. We perform additional steps to ensure that secure data (e.g., environment variables or other forms of sensitive data) **do not** make their way into our analytics. You can view all the information we collect by setting the `STORYBOOK_TELEMETRY_DEBUG` to `1` to print out the information gathered. For example:

```shell
STORYBOOK_TELEMETRY_DEBUG=1 npm run storybook
```

```shell
STORYBOOK_TELEMETRY_DEBUG=1 yarn storybook
```

Will generate the following output:

```json
{
  "anonymousId": "8bcfdfd5f9616a1923dd92adf89714331b2d18693c722e05152a47f8093392bb",
  "eventType": "dev",
  "context": {
    "isTTY": true,
    "platform": "macOS",
    "nodeVersion": "24.11.0",
    "storybookVersion": "10.3.0-alpha.9",
    "cliVersion": "10.3.0-alpha.9",
    "projectSince": 1717334400000
  },
  "payload": {
    "versionStatus": "cached",
    "storyIndex": {
      "storyCount": 0,
      "componentCount": 0,
      "pageStoryCount": 0,
      "playStoryCount": 0,
      "autodocsCount": 0,
      "mdxCount": 0,
      "exampleStoryCount": 8,
      "exampleDocsCount": 3,
      "onboardingStoryCount": 0,
      "onboardingDocsCount": 0,
      "version": 5
    },
    "storyStats": {
      "factory": 0,
      "play": 0,
      "render": 1,
      "loaders": 0,
      "beforeEach": 0,
      "globals": 0,
      "storyFn": 5,
      "mount": 0,
      "moduleMock": 0,
      "tags": 0
    }
  },
  "metadata": {
    "generatedAt": 1689007841223,
    "settingsCreatedAt": 1689007841223,
    "hasCustomBabel": false,
    "hasCustomWebpack": false,
    "hasStaticDirs": false,
    "hasStorybookEslint": false,
    "refCount": 0,
    "portableStoriesFileCount": 0,
    "packageManager": {
      "type": "yarn",
      "version": "3.1.1"
    },
    "monorepo": "Nx",
    "framework": {
      "name": "@storybook/react-vite",
      "options": {}
    },
    "builder": "@storybook/builder-vite",
    "renderer": "@storybook/react",
    "storybookVersion": "9.0.0",
    "storybookVersionSpecifier": "^9.0.0",
    "language": "typescript",
    "storybookPackages": {
      "@storybook/addon-docs/blocks": {
        "version": "9.0.0"
      },
      "@storybook/react": {
        "version": "9.0.0"
      },
      "@storybook/react-vite": {
        "version": "9.0.0"
      },
      "storybook": {
        "version": "9.0.0"
      }
    },
    "addons": {
      "@storybook/addon-onboarding": {
        "version": "1.0.6"
      }
    }
  }
}
```

Additionally, if Storybook's guided tour is enabled, it will generate the following output:

```json
{
  "eventType": "addon-onboarding",
  "payload": {
    "step": "1:Welcome",
    "addonVersion": "1.0.6"
  },
  "metadata": {
    // See above for metadata that's collected.
  }
}
```

## Will this data be shared?

The data we collect is anonymous, not traceable to the source, and only meaningful in aggregate form. No data we collect is personally identifiable.
In the future, we plan to share relevant data with the community through public dashboards (or similar data representation formats).

## How to opt-out

You may opt out of the telemetry within your Storybook configuration by setting the `disableTelemetry` configuration element to `true`.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableTelemetry: true, // 👈 Disables telemetry
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableTelemetry: true, // 👈 Disables telemetry
  },
});
```

If necessary, you can also turn off telemetry via the command line with the `--disable-telemetry` flag.

```shell
npm run storybook -- --disable-telemetry
```

```shell
pnpm run storybook --disable-telemetry
```

```shell
yarn storybook --disable-telemetry
```

Or via the `STORYBOOK_DISABLE_TELEMETRY` environment variable.

```shell
STORYBOOK_DISABLE_TELEMETRY=true yarn storybook
```

There is a `boot` event containing no metadata (used to ensure the telemetry is working). It is sent prior to evaluating your [Storybook configuration file](https://storybook.js.org/docs/api/main-config/main-config.md) (i.e., `main.js|ts`), so it is unaffected by the `disableTelemetry` option. If you want to ensure that the event is not sent, use the `STORYBOOK_DISABLE_TELEMETRY` environment variable.

## Crash reports (disabled by default)

In addition to general usage telemetry, you may also choose to share crash reports. Storybook will then sanitize the error object (removing all user paths) and append it to the telemetry event. To enable crash reporting, you can set the `enableCrashReports` configuration element to `true`.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    enableCrashReports: true, // 👈 Appends the crash reports to the telemetry events
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    enableCrashReports: true, // 👈 Appends the crash reports to the telemetry events
  },
});
```

You can also enable crash reporting via the command line with the `--enable-crash-reports` flag.

```shell
npm run storybook -- --enable-crash-reports
```

```shell
pnpm run storybook --enable-crash-reports
```

```shell
yarn storybook --enable-crash-reports
```

Or by setting the `STORYBOOK_ENABLE_CRASH_REPORTS` environment variable to `1`.

```shell
STORYBOOK_ENABLE_CRASH_REPORTS=1 yarn storybook
```

Enabling any of the options will generate the following item in the telemetry event:

```js
{
  stack: 'Error: Your button is not working\n' +
    '    at Object.<anonymous> ($SNIP/test.js:39:27)\n' +
    '    at Module._compile (node:internal/modules/cjs/loader:1103:14)\n' +
    '    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1157:10)\n' +
    '    at Module.load (node:internal/modules/cjs/loader:981:32)\n' +
    '    at Function.Module._load (node:internal/modules/cjs/loader:822:12)\n' +
    '    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:77:12)\n' +
    '    at node:internal/main/run_main_module:17:47',
  message: 'Your button is not working'
}
```
> Source: https://storybook.js.org/docs/configure/telemetry
---

# Framework support

Frameworks are packages that auto-configure Storybook to work with most common environment setups. They simplify the setup process and reduce boilerplate by mirroring your framework's conventions to create applications.

## How do frameworks work in Storybook?

You start by [installing](https://storybook.js.org/docs/get-started/install.md) Storybook into an existing project. Then, it tries to detect the framework you're using and automatically configures Storybook to work with it. That means adding the necessary libraries as dependencies and adjusting the configuration. Finally, starting Storybook will automatically load the framework configuration before loading any existing addons to match your application environment.

## Which frameworks are supported?

Storybook provides support for the leading industry builders and frameworks. However, that doesn't mean you can't use Storybook with other frameworks. Below is a list of currently supported frameworks divided by their builders.

| Builder | Framework                                                                  |
| ------- | -------------------------------------------------------------------------- |
| Webpack | React, Angular, Vue 3, Web Components, NextJS, HTML, Ember, Preact, Svelte |
| Vite    | React, Vue 3, Web Components, HTML, Svelte, SvelteKit, Qwik, Solid         |

### What about feature support?

In addition to supporting the most popular frameworks in the industry, Storybook also tries to retain the same level of feature support for each framework, including the addon ecosystem. For more information, see [Framework support](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md) for a comprehensive list of which features and addons are currently maintained with the community's help.

## Configure

Every modern web application has unique requirements and relies on various tools and frameworks. By default, with Storybook, you get an out-of-the-box configuration generated to work with most frameworks. However, you can extend your existing configuration file (i.e., `./storybook/main.js|ts|cjs`) and provide additional options. Below is an abridged table with available options and examples of configuring Storybook for your framework.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const config: StorybookConfig = {
  framework: {
    name: '@storybook/your-framework',
    options: {
      legacyRootApi: true,
    },
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: {
    name: '@storybook/your-framework',
    options: {
      legacyRootApi: true,
    },
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
});
```

| Option           | Description                                                                                                                                                                                                                                                  | Framework |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `nextConfigPath` | Sets the default path for the NextJS configuration file<br />`framework: { name: '@storybook/nextjs', options: { nextConfigPath: '../next.config.js'} }`                                                                                                     | NextJS    |
| `builder`        | Configures [Webpack 5](https://storybook.js.org/docs/builders/webpack.md) builder options for NextJS<br /> `core: { builder: { name:'webpack5', options: { lazyCompilation: true} }}`                                                                                               | NextJS    |
| `strictMode`     | Enables React's [strict mode](https://reactjs.org/docs/strict-mode.html)<br />`framework: { name: '@storybook/react-webpack5', options: { strictMode: false } }`                                                                                             | React     |
| `legacyRootApi`  | Requires React 18. Toggles support for React's [legacy root API](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis)<br />`framework: { name: '@storybook/react-webpack5', options: { legacyRootApi: true } }` | React     |
| `enableIvy`      | Enabled by default with Angular 9+. Replaces the default compiler with the [Ivy compiler](https://docs.angular.lat/guide/ivy)<br />`framework: { name: '@storybook/angular', options: { enableIvy: true } }`                                                 | Angular   |
| `enableNgcc`     | Enabled by default with Angular 9+. Adds support for ngcc for backwards compatibility<br />`framework: { name: '@storybook/angular', options: { enableNgcc: false } }`                                                                                       | Angular   |

---

## Troubleshooting

### NextJS 13 doesn't work with Storybook

With the release of Next.js [version 13](https://nextjs.org/blog/next-13), it introduced breaking changes (e.g., [TurboPack](https://turbo.build/pack), [Server Components](https://nextjs.org/docs/advanced-features/react-18/server-components)) that are not yet fully supported by Storybook. The Storybook team is working on adding support for these features. In the meantime, you can still use Storybook alongside your Next.js 13 project if you're not relying on them.

### My framework doesn't work with Storybook

Out of the box, most frameworks work seamlessly with Storybook. However, some frameworks (e.g., [CRACO](https://craco.js.org/)) provide their own configuration that Storybook isn't prepared to handle without additional steps, either [via addon](https://storybook.js.org/docs/addons/writing-presets.md) or integration. To learn more, read our [addons guide](https://storybook.js.org/docs/addons.md).

### How do I build a Storybook framework?

Storybook is a framework-agnostic tool. It can be used with any framework. However, to make it easier for you to get started, we provide instructions that you can use to build your framework. To learn more, read our [frameworks guide](https://storybook.js.org/docs/contribute/framework.md).

### Legacy framework support

We're deprecating support for several frameworks, including [Aurelia](https://github.com/aurelia/framework), [Marionette](https://github.com/marionettejs/backbone.marionette), [Mithril](https://github.com/MithrilJS/mithril.js), [Rax](https://github.com/alibaba/rax), and [Riot](https://github.com/riot/riot). Nevertheless, we're always looking for help maintaining these frameworks. If you're working with one of them and you want to continue supporting them, visit the dedicated [Storybook End-of-Life repository](https://github.com/storybook-eol). To learn more about the sunsetting process and view instructions on how to contribute, read our [documentation](https://storybook.js.org/docs/contribute.md).

### Learn about configuring Storybook

- [Theming](https://storybook.js.org/docs/configure/user-interface/theming.md) to customize the look and feel of Storybook's UI
- [CSS](https://storybook.js.org/docs/configure/styling-and-css.md) to configure CSS support
- [Images & assets](https://storybook.js.org/docs/configure/integration/images-and-assets.md) for static asset handling
- [Environment variables](https://storybook.js.org/docs/configure/environment-variables.md) to configure environment variables
> Source: https://storybook.js.org/docs/configure/integration/frameworks
---

# Feature support for frameworks

Storybook integrates with many popular frontend frameworks. We do our best to keep feature parity amongst frameworks, but it’s tricky for our modest team to support every framework.

Below is a comprehensive table of what’s supported in which framework integration. If you’d like a certain feature supported in your framework, we welcome pull requests.

## Core frameworks

Core frameworks have dedicated maintainers or contributors who are responsible for maintaining the integration. As such, you can use most Storybook features in these frameworks.

|                                                                                         | React | Vue 3 | Angular | Web Components |
| --------------------------------------------------------------------------------------- | ----- | ----- | ------- | -------------- |
| **Essentials**                                                                          |       |       |         |                |
| [Actions](https://storybook.js.org/docs/essentials/actions.md)                                                 | ✅    | ✅    | ✅      | ✅             |
| [Backgrounds](https://storybook.js.org/docs/essentials/backgrounds.md)                                         | ✅    | ✅    | ✅      | ✅             |
| [Controls](https://storybook.js.org/docs/essentials/controls.md)                                               | ✅    | ✅    | ✅      | ✅             |
| [Interactions](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests) | ✅    | ✅    | ✅      | ✅             |
| [Measure](https://storybook.js.org/docs/essentials/measure-and-outline.md#measure)                             | ✅    | ✅    | ✅      | ✅             |
| [Outline](https://storybook.js.org/docs/essentials/measure-and-outline.md#outline)                             | ✅    | ✅    | ✅      | ✅             |
| [Viewport](https://storybook.js.org/docs/essentials/viewport.md)                                               | ✅    | ✅    | ✅      | ✅             |
| **Addons**                                                                              |       |       |         |                |
| [A11y](https://storybook.js.org/docs/writing-tests/accessibility-testing.md)                                   | ✅    | ✅    | ✅      | ✅             |
| [Docs](https://storybook.js.org/docs/writing-docs.md)                                                    | ✅    | ✅    | ✅      | ✅             |
| [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md)                         | ✅    | ✅    | ✅      | ✅             |
| [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md)                                  | ✅    | ✅    | ✅      | ✅             |
| [CSS resources](https://github.com/storybookjs/addon-cssresources)                      | ✅    | ✅    | ✅      | ✅             |
| [Design assets](https://github.com/storybookjs/addon-design-assets)                     | ✅    | ✅    | ✅      | ✅             |
| [Events](https://github.com/storybookjs/addon-events)                                   | ✅    | ✅    | ✅      | ✅             |
| [Google analytics](https://github.com/storybookjs/addon-google-analytics)               | ✅    | ✅    | ✅      | ✅             |
| [GraphQL](https://github.com/storybookjs/addon-graphql)                                 | ✅    |       | ✅      |                |
| [Jest](https://github.com/storybookjs/addon-jest)                                       | ✅    | ✅    | ✅      | ✅             |
| [Links](https://github.com/storybookjs/storybook/tree/next/code/addons/links)           | ✅    | ✅    | ✅      | ✅             |
| [Queryparams](https://github.com/storybookjs/addon-queryparams)                         | ✅    | ✅    | ✅      | ✅             |
| **Docs**                                                                                |       |       |         |                |
| [CSF Stories](https://storybook.js.org/docs/api/csf.md)                                                  | ✅    | ✅    | ✅      | ✅             |
| [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md)                                             | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - ArgTypes](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md)                    | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Canvas](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md)                        | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - ColorPalette](https://storybook.js.org/docs/api/doc-blocks/doc-block-colorpalette.md)            | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Controls](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md)                    | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Description](https://storybook.js.org/docs/api/doc-blocks/doc-block-description.md)              | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - IconGallery](https://storybook.js.org/docs/api/doc-blocks/doc-block-icongallery.md)              | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Markdown](https://storybook.js.org/docs/api/doc-blocks/doc-block-markdown.md)                    | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Meta](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md)                            | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Primary](https://storybook.js.org/docs/api/doc-blocks/doc-block-primary.md)                      | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Source](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md)                        | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Story](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md)                          | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Stories](https://storybook.js.org/docs/api/doc-blocks/doc-block-stories.md)                      | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Subtitle](https://storybook.js.org/docs/api/doc-blocks/doc-block-subtitle.md)                    | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Title](https://storybook.js.org/docs/api/doc-blocks/doc-block-title.md)                          | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Typeset](https://storybook.js.org/docs/api/doc-blocks/doc-block-typeset.md)                      | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - Unstyled](https://storybook.js.org/docs/api/doc-blocks/doc-block-unstyled.md)                    | ✅    | ✅    | ✅      | ✅             |
| [Doc Blocks - UseOf](https://storybook.js.org/docs/api/doc-blocks/doc-block-useof.md)                          | ✅    | ✅    | ✅      | ✅             |
| Inline stories                                                                          | ✅    | ✅    | ✅      | ✅             |

## Community frameworks

Community frameworks have fewer contributors which means they may not be as up to date as core frameworks. If you use one of these frameworks for your job, please consider contributing to its integration with Storybook.

|                                                                                         | Ember | HTML | Svelte | Preact | Qwik | SolidJS |
| --------------------------------------------------------------------------------------- | ----- | ---- | ------ | ------ | ---- | ------- |
| **Essentials**                                                                          |       |      |        |        |      |         |
| [Actions](https://storybook.js.org/docs/essentials/actions.md)                                                 | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Backgrounds](https://storybook.js.org/docs/essentials/backgrounds.md)                                         | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Controls](https://storybook.js.org/docs/essentials/controls.md)                                               | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Interactions](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests) |       | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Measure](https://storybook.js.org/docs/essentials/measure-and-outline.md#measure)                             | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Outline](https://storybook.js.org/docs/essentials/measure-and-outline.md#outline)                             | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Viewport](https://storybook.js.org/docs/essentials/viewport.md)                                               | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| **Addons**                                                                              |       |      |        |        |      |         |
| [A11y](https://storybook.js.org/docs/writing-tests/accessibility-testing.md)                                   | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Docs](https://storybook.js.org/docs/writing-docs.md)                                                    | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Test runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner.md)                         |       | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Test coverage](https://storybook.js.org/docs/writing-tests/test-coverage.md)                                  |       | ✅   | ✅     | ✅     | ✅   | ✅      |
| [CSS resources](https://github.com/storybookjs/addon-cssresources)                      | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Design assets](https://github.com/storybookjs/addon-design-assets)                     | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Events](https://github.com/storybookjs/addon-events)                                   | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Google analytics](https://github.com/storybookjs/addon-google-analytics)               | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [GraphQL](https://github.com/storybookjs/addon-graphql)                                 |       |      |        |        |      |         |
| [Jest](https://github.com/storybookjs/addon-jest)                                       | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Links](https://github.com/storybookjs/storybook/tree/next/code/addons/links)           | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Queryparams](https://github.com/storybookjs/addon-queryparams)                         | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| **Docs**                                                                                |       |      |        |        |      |         |
| [CSF Stories](https://storybook.js.org/docs/api/csf.md)                                                  | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md)                                             |       | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - ArgTypes](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md)                    | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Canvas](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md)                        | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - ColorPalette](https://storybook.js.org/docs/api/doc-blocks/doc-block-colorpalette.md)            | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Controls](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md)                    | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Description](https://storybook.js.org/docs/api/doc-blocks/doc-block-description.md)              | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - IconGallery](https://storybook.js.org/docs/api/doc-blocks/doc-block-icongallery.md)              | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Markdown](https://storybook.js.org/docs/api/doc-blocks/doc-block-markdown.md)                    | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Meta](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md)                            | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Primary](https://storybook.js.org/docs/api/doc-blocks/doc-block-primary.md)                      | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Source](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md)                        | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Story](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md)                          | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Stories](https://storybook.js.org/docs/api/doc-blocks/doc-block-stories.md)                      | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Subtitle](https://storybook.js.org/docs/api/doc-blocks/doc-block-subtitle.md)                    | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Title](https://storybook.js.org/docs/api/doc-blocks/doc-block-title.md)                          | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Typeset](https://storybook.js.org/docs/api/doc-blocks/doc-block-typeset.md)                      | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - Unstyled](https://storybook.js.org/docs/api/doc-blocks/doc-block-unstyled.md)                    | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| [Doc Blocks - UseOf](https://storybook.js.org/docs/api/doc-blocks/doc-block-useof.md)                          | ✅    | ✅   | ✅     | ✅     | ✅   | ✅      |
| Inline stories                                                                          |       | ✅   | ✅     |        |      |         |

## Deprecated

To align the Storybook ecosystem with the current state of frontend development, the following features and addons are now deprecated, no longer maintained, and will be removed in future versions of Storybook

| Feature                                             | Status                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Knobs](https://github.com/storybookjs/addon-knobs) | The Knobs addon was officially deprecated with the release of Storybook 6.3 and is no longer actively maintained. We recommend using the [controls](https://storybook.js.org/docs/essentials/controls.md) instead.                                                                                                                                       |
| Storyshots                                          | The Storyshots addon was officially deprecated with the release of Storybook 7.6, is no longer actively maintained and was removed in Storybook 8. See the [migration guide](https://storybook.js.org/docs/8/writing-tests/snapshot-testing/storyshots-migration-guide.md) for the available alternatives.                             |
| StoriesOf                                           | The `storiesOf` API was officially removed with the release of Storybook 8 and is no longer maintained. We recommend using the [CSF API](https://storybook.js.org/docs/api/csf.md) instead for writing stories.<br />See the [migration guide](https://storybook.js.org/docs/releases/migration-guide-from-older-version.md#major-breaking-changes) for more information. |
| Storysource                                         | The Storysource addon was officially removed with the release of Storybook 9 and is no longer maintained. To display your stories' source code, we recommend using the [`codePanel`](https://storybook.js.org/docs/writing-docs/code-panel.md) parameter instead.                                                                                        |
> Source: https://storybook.js.org/docs/configure/integration/frameworks-feature-support
---

# Compiler support

Javascript compilers are essential in optimizing and transforming code, enhancing performance, and ensuring compatibility across different environments. Storybook provides support for the leading compilers, ensuring lightning-fast build time and execution with [SWC](https://swc.rs/) or leveraging [Babel](https://babeljs.io/) with its extensive ecosystem of plugins and presets to allow you to use the latest features of the ecosystem with minimal configuration required for your Webpack-based project.

## SWC

SWC is a fast, highly extensible tool for compiling and bundling modern JavaScript applications. Powered by [Rust](https://www.rust-lang.org/), it improves performance and reduces build times. Storybook includes a built-in integration with SWC, allowing zero-configuration setup and built-in types for APIs. If you've initialized Storybook in a Webpack-based project with any of the supported [frameworks](https://storybook.js.org/docs/configure/integration/frameworks.md), except Angular, Create React App, Ember.js and Next.js, it will automatically use SWC as its default, providing you with faster loading time.

Support for the SWC builder is currently experimental for Next.js projects, and it's not enabled by default. It requires you to opt in to use it. For more information on configuring SWC with the supported frameworks, see the [SWC API](https://storybook.js.org/docs/api/main-config/main-config-swc.md) documentation.

## Babel

Babel is a widely adopted JavaScript compiler providing a modular architecture and extensive plugin system to support a wide range of use cases, enabling access to the cutting-edge features of the tooling ecosystem. Storybook provides a seamless integration with Babel, allowing you to share a standard setup between your project and Storybook without any additional configuration.

If you're not using Storybook 7, please reference the [previous documentation](https://storybook.js.org/docs/6/configure/babel.md) for guidance on configuring your Babel setup.

### Configure

By default, Babel provides an opinionated [configuration](https://babeljs.io/docs/config-files) that works for most projects, relying on two distinct methods for configuring projects with the tool:

- **Project-wide configuration**: Babel will look for a `babel.config.js` or equivalent file in the root of your project and use it to configure your project's Babel setup.
- **File-relative configuration**: Babel will look for a `.babelrc.json` or equivalent file, introspecting the project structure until it finds a configuration file. This will allow you to configure Babel individually for multiple aspects of your project.

Storybook relies on an agnostic approach to configuring Babel, enabling you to provide the necessary configuration for your project, and it will use it. Based on the supported frameworks, builders, and addons, it may include minor adjustments to ensure compatibility with Storybook's features.

For custom project configurations such as monorepos, where you have multiple Storybook configurations, creating a `.babelrc.json` file in your project's current working directory may not be sufficient. In those cases, you can create a `babel.config.js` file to override Babel's configuration, and Storybook will automatically detect and use it. See the Babel [documentation](https://babeljs.io/docs/config-files) for more information.

### Working with Create React App

If you're working with a project that was initialized with [Create React App](https://create-react-app.dev/), Storybook will automatically detect and use the Babel configuration provided by the tool enabled via the `@storybook/preset-create-react-app` preset, allowing to use Storybook without any additional configuration.

## Troubleshooting

### The SWC compiler doesn't work with React

If you have enabled the SWC builder option in a React-based project and you are not explicitly importing React in your `jsx|tsx` files, it can cause Storybook to fail to load. SWC does not automatically import the `jsx-runtime` module when using the SWC builder. To resolve this issue, you need to adjust your Storybook configuration file (i.e., `.storybook/main.js|ts`) and configure the `swc` option as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the webpack-based framework you are using (e.g., react-webpack5)

const config: StorybookConfig = {
  framework: {
    name: '@storybook/your-framework',
    options: {},
  },
  swc: (config, options) => ({
    jsc: {
      transform: {
        react: {
          runtime: 'automatic',
        },
      },
    },
  }),
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: {
    name: '@storybook/your-framework',
    options: {},
  },
  swc: (config, options) => ({
    jsc: {
      transform: {
        react: {
          runtime: 'automatic',
        },
      },
    },
  }),
});
```

### Babel configuration not working

Out of the box, Storybook can detect and apply any Babel configuration you provided in your project. However, if you're running into a situation where your configuration is not being used, you configure the [`BABEL_SHOW_CONFIG_FOR`](https://babeljs.io/docs/configuration#print-effective-configs) environment variable and set it to the file you want to inspect. For example:

```sh
BABEL_SHOW_CONFIG_FOR=.storybook/preview.js yarn storybook
```

When the command runs, it will output the Babel configuration applied to the file you specified despite showing a transpilation error in the console and preventing Storybook from loading. This is a known issue with Babel unrelated to Storybook, which you address by turning off the environment variable after inspecting the configuration and restarting Storybook.
> Source: https://storybook.js.org/docs/configure/integration/compilers
---

# TypeScript

Storybook provides an integrated [TypeScript](https://www.typescriptlang.org/) experience, including zero-configuration setup and built-in types for APIs, addons, and stories.

## Configure Storybook with TypeScript

Storybook's configuration file (i.e., `main.ts`) is defined as an ESM module written in TypeScript, providing you with the baseline configuration to support your existing framework while enabling you stricter type-checking and autocompletion in your editor. Below is an abridged configuration file.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-docs'],
  staticDirs: ['../public'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-docs'],
  staticDirs: ['../public'],
});
```

See the [main configuration API reference](https://storybook.js.org/docs/api/main-config/main-config.md) for more details and additional properties.

See the Vite builder [TypeScript documentation](https://github.com/storybookjs/builder-vite#typescript) if using `@storybook/builder-vite`.

### Extending the default configuration

Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props, inputs) from your components without any additional configuration. Since Storybook supports multiple frameworks, it also includes a set of third-party packages to support each framework (e.g., `ts-loader`, `vue-docgen-api` for Vue). If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them.

| Option         | Description                                                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `check`        | Available for Webpack-based projects.<br />Enables type checking within Storybook<br />`typescript: { check: true },`                                                                                          |
| `checkOptions` | Requires the `check` option to be enabled.<br />Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin<br />`typescript: { checkOptions:{},},` |
| `skipCompiler` | Disables parsing Typescript files through the compiler<br />`typescript: { skipCompiler:false,},`                                                                                                              |

Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props) for your components without any additional configuration. It relies on [`react-docgen`](https://github.com/reactjs/react-docgen), a fast and highly customizable parser to process TypeScript files to infer the component's metadata and generate types automatically for improved performance and type safety. If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them.

| Option                         | Description                                                                                                                                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `check`                        | Available for Webpack-based projects.<br />Enables type checking within Storybook<br />`typescript: { check: true },`                                                                                                                       |
| `checkOptions`                 | Requires the `check` option to be enabled.<br />Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin<br />`typescript: { checkOptions: {},},`                             |
| `reactDocgen`                  | Configures the TypeScript parser used by Storybook.<br />Available options: `react-docgen` (default), `react-docgen-typescript`,` false`<br /> `typescript: { reactDocgen: 'react-docgen'},`                                                |
| `reactDocgenTypescriptOptions` | Requires the `reactDocgen`option to be `react-docgen-typescript`.<br /> Configures the `react-docgen-typescript-plugin` plugin per builder<br />`typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: {},},` |
| `skipCompiler`                 | Disables parsing Typescript files through the compiler<br />`typescript: { skipCompiler:false,},`                                                                                                                                           |

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: false,
    checkOptions: {},
    skipCompiler: false,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: false,
    checkOptions: {},
    skipCompiler: false,
  },
});
```

Additional options are available for the `typescript` configuration option. See the [`config.typescript` API reference](https://storybook.js.org/docs/api/main-config/main-config-typescript.md) for more information.

## Write stories with TypeScript

Storybook provides zero-config TypeScript support, allowing you to write stories using this language without additional configuration. You can use this format for improved type safety and code completion. For example, if you're testing a `Button` component, you could do the following in your story file:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

//👇 Throws a type error if the args don't match the component props
export const Primary: Story = {
  args: {
    primary: true,
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

//👇 Throws a type error if the args don't match the component props
export const Primary = meta.story({
  args: {
    primary: true,
  },
});
```

The example above uses the power of TypeScript in combination with the exported generic types (`Meta` and `StoryObj`) to tell Storybook how to infer the component's metadata and the type of the component's inputs (e.g., props). This can greatly improve the developer experience by letting your IDE show you what properties are injected by Storybook.

### TypeScript 4.9 support

Assuming that you're working on a project that uses TypeScript 4.9+, you can update your component stories to use the new [`satisfies`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html) operator to ensure stricter type checking for your component stories. For example:

```ts
// Button.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
} satisfies Meta<typeof Button>; // 👈 Satisfies operator being used for stricter type checking.

export default meta;
```

Now, when you define a story or update an existing one, you'll automatically get notified that you're missing a required [`arg`](https://storybook.js.org/docs/writing-stories/args.md). However, you're not limited to using the `satisfies` operator at the component level. If you need, you can also use it at the story level. For example:

```ts
// Button.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Example = {
  args: {
    primary: true,
    label: 'Button',
  },
} satisfies Story;
```

## Troubleshooting

### The `satisfies` operator is not working as expected

Out of the box, Storybook supports the `satisfies` operator for almost every framework already using TypeScript version 4.9 or higher. However, due to the constraints of the Angular and Web Components framework, you might run into issues when applying this operator for additional type safety. This is primarily due to how both frameworks are currently implemented, making it almost impossible for Storybook to determine if the component property is required. If you encounter this issue, please open up a support request on [GitHub Discussions](https://github.com/storybookjs/storybook/discussions/new?category=help).

### The TypeScript auto-completion is not working on my editor

If you're using Vue single file components and TypeScript, you can add the official [Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar) extension for editor support, additional type safety and auto-completion. Nevertheless, if you're working with Svelte, you can add the [Svelte for VSCode extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) for similar benefits.

### Storybook doesn't create the required types for external packages

If your project relies on a third-party library and the expected types are not being generated, preventing you from accurately documenting your components, you can adjust the `reactDocgen` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead and include the required options. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      compilerOptions: {
        allowSyntheticDefaultImports: false,
        esModuleInterop: false,
      },
      // Filter out third-party props from node_modules except @mui packages.
      propFilter: (prop) =>
        prop.parent ? !/node_modules\/(?!@mui)/.test(prop.parent.fileName) : true,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      compilerOptions: {
        allowSyntheticDefaultImports: false,
        esModuleInterop: false,
      },
      // Filter out third-party props from node_modules except @mui packages.
      propFilter: (prop) =>
        prop.parent ? !/node_modules\/(?!@mui)/.test(prop.parent.fileName) : true,
    },
  },
});
```

### Inherited args are missing for components from workspace packages

If you're using `react-docgen-typescript` in a monorepo with npm/yarn/pnpm workspaces, you may find that components imported from a workspace package are missing inherited args (e.g., MUI's `ButtonProps`), while the same component imported locally works fine.

This happens because the underlying Vite plugin creates a TypeScript program from files matching its `include` glob (default: `**/**.tsx`), resolved from the Storybook project's directory. Workspace package files are outside that directory and aren't included in the program, so inherited types can't be resolved.

To fix this, add your workspace package source files to the `include` option:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      // 👇 Add your workspace package source files so they're included in the TS program
      include: ['**/*.tsx', '../../packages/ui/src/**/*.tsx'],
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      // 👇 Add your workspace package source files so they're included in the TS program
      include: ['**/*.tsx', '../../packages/ui/src/**/*.tsx'],
    },
  },
});
```

Adjust the path (`../../packages/ui/src/**/*.tsx`) to match your monorepo layout. You might expect that pointing `tsconfigPath` to a tsconfig that includes your workspace packages would solve this, but `tsconfigPath` only affects which compiler options are used. It does not change which files are included in the TypeScript program.

### The types are not being generated for my component

If you're working with a React project, type inference is automatically enabled for your components using the `react-docgen` library for improved build times and type safety. However, you may run into a situation where some options may not work as expected (e.g., [`Enums`](https://www.typescriptlang.org/docs/handbook/enums.html), React's [`forwardRef`](https://react.dev/reference/react/forwardRef)). This is primarily due to how the `react-docgen` package is implemented, making it difficult for Storybook to infer the component's metadata and generate types automatically. To solve this, you can update the `typescript` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    // Provide your own options if necessary.
    // See https://storybook.js.org/docs/configure/typescript for more information.
    reactDocgenTypescriptOptions: {},
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    // Provide your own options if necessary.
    // See https://storybook.js.org/docs/configure/typescript for more information.
    reactDocgenTypescriptOptions: {},
  },
});
```

If you're still encountering issues, we recommend reaching out to the community using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)).
> Source: https://storybook.js.org/docs/configure/integration/typescript
---

# ESLint plugin

Storybook provides a dedicated [ESLint plugin](https://github.com/storybookjs/storybook/tree/next/code/lib/eslint-plugin) to help you write stories and components aligned with the latest Storybook and frontend development best practices.

## Installation

You'll first need to install [ESLint](https://eslint.org/):

```shell
npm install --save-dev eslint
```

```shell
pnpm add --save-dev eslint
```

```shell
yarn add --dev eslint
```

Next, install `eslint-plugin-storybook`:

```shell
npm install --save-dev eslint-plugin-storybook
```

```shell
pnpm add --save-dev eslint-plugin-storybook
```

```shell
yarn add --dev eslint-plugin-storybook
```

Then add `plugin:storybook/recommended` to the extends section of your `.eslintrc` configuration file. Note that we can omit the `eslint-plugin-` prefix:

```js title=".eslintrc"
{
  // extend plugin:storybook/<configuration>, such as:
  "extends": ["plugin:storybook/recommended"]
}
```

And finally, add this to your `.eslintignore` file:

```txt title=".eslintignore"
!.storybook
```

This ensures that the plugin will also lint your configuration files inside the `.storybook` directory, so that you always have a correct configuration. For example, it can catch mistyped addon names in your `main.js|ts` file.

For more details on why this line is required in the `.eslintignore` file, refer to the [ESLint documentation](https://eslint.org/docs/latest/use/configure/ignore-deprecated#:~:text=In%20addition%20to,contents%20are%20ignored).

If you are using [flat config style](https://eslint.org/docs/latest/use/configure/configuration-files-new), add this to your configuration file:

```js title="eslint.config.js"

export default defineConfig([
  globalIgnores(['!.storybook'], 'Include Storybook Directory'),
  // ...
]);
```

## ESLint compatibility

Depending on the version of ESLint you are using, you may need to install a specific version of the Storybook plugin. Use the table below to match the plugin version to your ESLint version.

| ESLint version | Storybook plugin version |
| -------------- | ------------------------ |
| `^9.0.0`       | `^9.0.0` or `^0.10.0`    |
| `^8.57.0`      | `^9.0.0` or `^0.10.0`    |
| `^7.0.0`       | `~0.9.0`                 |

## Usage

### Configuration (`.eslintrc`)

Use `.eslintrc.*` file to configure rules in ESLint < v9. [ESLint docs](https://eslint.org/docs/latest/use/configure/).

This plugin will only be applied to files following the `*.stories.*` (recommended) or `*.story.*` pattern. This is an automatic configuration, so no action is required.

#### Overriding/disabling rules

Optionally, you can override, add to, or disable individual rules. You likely don't want these settings to be applied in every file, so make sure that you add a `overrides` section in your `.eslintrc.*` file that applies the overrides only to your story files.

```js title=".eslintrc"
{
  "overrides": [
    {
      // 👇 This should match the `stories` property in .storybook/main.js|ts
      "files": ["**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)"],
      "rules": {
        // 👇 Enable this rule
        "storybook/csf-component": "error",
        // 👇 Disable this rule
        "storybook/default-exports": "off",
      }
    }
  ]
}
```

### Configuration (flat config format)

Use the `eslint.config.js` file to configure rules using the [flat config style](https://eslint.org/docs/latest/use/configure/configuration-files-new). This is the default in ESLint v9, but can be used starting from ESLint v8.57.0. [ESLint docs](https://eslint.org/docs/latest/use/configure/configuration-files-new).

```js title="eslint.config.js"

// Replace the eslint/config package with @eslint/config-helpers if you're using an older version of ESLint.

export default defineConfig([
  ...storybook.configs['flat/recommended'],
  // Add more configuration options and generic rulesets here, such as js.configs.recommended
]);
```

In case you are using utility functions from tools like `tseslint`, you might need to register the plugin a little differently:

```ts title="eslint.config.ts"

export default tseslint.config(
  somePlugin,
  storybook.configs['flat/recommended'], // notice that it is not destructured
);
```

#### Overriding/disabling rules

Optionally, you can override, add, or disable individual rules. You likely don't want these settings to be applied to every file, so ensure that you add a flat config section in your `eslint.config.js` file that applies the overrides only to your story files.

```js title="eslint.config.js"

export default defineConfig([
  ...storybook.configs['flat/recommended'],
  {
    // 👇 This should match the `stories` property in .storybook/main.js|ts
    files: ['**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)'],
    rules: {
      // 👇 Enable this rule
      'storybook/csf-component': 'error',
      // 👇 Disable this rule
      'storybook/default-exports': 'off',
    },
  },
]);
```

### MDX Support

This plugin does not support MDX files.

## Supported Rules and configurations

**Configurations**: csf, csf-strict, addon-interactions, recommended

| Name                                                                                                                                                               | Description                                                                                                                   | Automatically fixable | Included in configurations                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [`storybook/await-interactions`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/await-interactions.md)                       | Interactions should be awaited                                                                                                | ✅                    | <ul><li>addon-interactions</li><li>flat/addon-interactions</li><li>recommended</li><li>flat/recommended</li></ul>              |
| [`storybook/context-in-play-function`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/context-in-play-function.md)           | Pass a context when invoking play function of another story                                                                   |                       | <ul><li>recommended</li><li>flat/recommended</li><li>addon-interactions</li><li>flat/addon-interactions</li></ul>              |
| [`storybook/csf-component`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/csf-component.md)                                 | The component property should be set                                                                                          |                       | <ul><li>csf</li><li>flat/csf</li><li>csf-strict</li><li>flat/csf-strict</li></ul>                                              |
| [`storybook/default-exports`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/default-exports.md)                             | Story files should have a default export                                                                                      | ✅                    | <ul><li>csf</li><li>flat/csf</li><li>recommended</li><li>flat/recommended</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
| [`storybook/hierarchy-separator`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/hierarchy-separator.md)                     | Deprecated hierarchy separator in title property                                                                              | ✅                    | <ul><li>csf</li><li>flat/csf</li><li>recommended</li><li>flat/recommended</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
| [`storybook/meta-inline-properties`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/meta-inline-properties.md)               | Meta should only have inline properties                                                                                       |                       | N/A                                                                                                                            |
| [`storybook/meta-satisfies-type`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/meta-satisfies-type.md)                     | Meta should use `satisfies Meta`                                                                                              | ✅                    | N/A                                                                                                                            |
| [`storybook/no-redundant-story-name`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/no-redundant-story-name.md)             | A story should not have a redundant name property                                                                             | ✅                    | <ul><li>csf</li><li>flat/csf</li><li>recommended</li><li>flat/recommended</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
| [`storybook/no-renderer-packages`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/no-renderer-packages.md)                   | Do not import renderer packages directly in stories                                                                           |                       | <ul><li>recommended</li><li>flat/recommended</li></ul>                                                                         |
| [`storybook/no-stories-of`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/no-stories-of.md)                                 | storiesOf is deprecated and should not be used                                                                                |                       | <ul><li>csf-strict</li><li>flat/csf-strict</li></ul>                                                                           |
| [`storybook/no-title-property-in-meta`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/no-title-property-in-meta.md)         | Do not define a title in meta                                                                                                 | ✅                    | <ul><li>csf-strict</li><li>flat/csf-strict</li></ul>                                                                           |
| [`storybook/no-uninstalled-addons`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/no-uninstalled-addons.md)                 | This rule identifies storybook addons that are invalid because they are either not installed or contain a typo in their name. |                       | <ul><li>recommended</li><li>flat/recommended</li></ul>                                                                         |
| [`storybook/prefer-pascal-case`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/prefer-pascal-case.md)                       | Stories should use PascalCase                                                                                                 | ✅                    | <ul><li>recommended</li><li>flat/recommended</li></ul>                                                                         |
| [`storybook/story-exports`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/story-exports.md)                                 | A story file must contain at least one story export                                                                           |                       | <ul><li>recommended</li><li>flat/recommended</li><li>csf</li><li>flat/csf</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
| [`storybook/use-storybook-expect`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/use-storybook-expect.md)                   | Use expect from `@storybook/test`, `storybook/test` or `@storybook/jest`                                                      | ✅                    | <ul><li>addon-interactions</li><li>flat/addon-interactions</li><li>recommended</li><li>flat/recommended</li></ul>              |
| [`storybook/use-storybook-testing-library`](https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/use-storybook-testing-library.md) | Do not use testing-library directly on stories                                                                                | ✅                    | <ul><li>addon-interactions</li><li>flat/addon-interactions</li><li>recommended</li><li>flat/recommended</li></ul>              |
> Source: https://storybook.js.org/docs/configure/integration/eslint-plugin
---

# Images, fonts, and assets

Components often rely on images, videos, fonts, and other assets to render as the user expects. There are many ways to use these assets in your story files.

## Import assets into stories

You can import any media assets by importing (or requiring) them. It works out of the box with our default config. But, if you are using a custom webpack config, you’ll need to add the [file loader](https://webpack.js.org/loaders/) to handle the required files.

Afterward, you can use any asset in your stories:

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

const image = {
  src: imageFile,
  alt: 'my image',
};

export const WithAnImage: Story = {
  render: () => <img src={image.src} alt={image.alt} />,
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

const image = {
  src: imageFile,
  alt: 'my image',
};

export const WithAnImage = meta.story({
  render: () => <img src={image.src} alt={image.alt} />,
});
```

## Serving static files via Storybook Configuration

We recommend serving static files via Storybook to ensure that your components always have the assets they need to load. We recommend this technique for assets that your components often use, like logos, fonts, and icons.

Configure a directory (or a list of directories) where your assets live when starting Storybook. Use the `staticDirs` configuration element in your main Storybook configuration file (i.e., `.storybook/main.js|ts`) to specify the directories:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
});
```

Here `../public` is your static directory. Now use it in a component or story like this.

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

// Assume image.png is located in the "public" directory.
export const WithAnImage: Story = {
  render: () => <img src="/image.png" alt="my image" />,
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

// Assume image.png is located in the "public" directory.
export const WithAnImage = meta.story({
  render: () => <img src="/image.png" alt="my image" />,
});
```

You can also pass a list of directories separated by commas without spaces instead of a single directory.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
});
```

Or even use a configuration object to define the directories:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: [{ from: '../my-custom-assets/images', to: '/assets' }],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: [{ from: '../my-custom-assets/images', to: '/assets' }],
});
```

When using Vite-based frameworks, additional directories may be copied to your build directory because of Vite's own [static asset handling](https://vite.dev/guide/assets#the-public-directory). You can set Vite's `publicDir` option to `false` to disable this behavior.

## Reference assets from a CDN

Upload your files to an online CDN and reference them. In this example, we’re using a placeholder image service.

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

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

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

export const WithAnImage: Story = {
  render: () => (
    <img src="https://storybook.js.org/images/placeholders/350x150.png" alt="My CDN placeholder" />
  ),
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const WithAnImage = meta.story({
  render: () => (
    <img src="https://storybook.js.org/images/placeholders/350x150.png" alt="My CDN placeholder" />
  ),
});
```

## Absolute versus relative paths

Sometimes, you may want to deploy your Storybook into a subpath, like `https://example.com/storybook`.

In this case, you need to have all your images and media files with relative paths. Otherwise, the browser cannot locate those files.

If you load static content via importing, this is automatic, and you do not have to do anything.

Suppose you are serving assets in a [static directory](#serving-static-files-via-storybook-configuration) along with your Storybook. In that case, you need to use relative paths to load images or use the base element.

## Referencing Fonts in Stories

After configuring Storybook to serve assets from your static folder, you can reference those assets in Storybook. For example, you can reference and apply a custom font to your stories. To do this, create a [`preview-head.html`](https://storybook.js.org/docs/configure/story-rendering.md) file inside the configuration directory (i.e., `.storybook`) and add a `<link />` tag to reference your font.

```html
// .storybook/preview-head.html

<link rel="preload" href="/fonts/my-font.woff2" />

<script src="https://use.typekit.net/xxxyyy.js"></script>
<script>
  try {
    Typekit.load();
  } catch (e) {}
</script>
```
> Source: https://storybook.js.org/docs/configure/integration/images-and-assets
---

# Story rendering

In Storybook, your stories render in a particular “preview” iframe (also called the Canvas) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a [builder](https://storybook.js.org/docs/builders.md) config, but you also may want to run some code for every story or directly control the rendered HTML to help your stories render correctly.

## Running code for every story

Code executed in the preview file (`.storybook/preview.ts|tsx`) runs for every story in your Storybook. This is useful for setting up global styles, initializing libraries, or anything else required to render your components.

Here's an example of how you might use the preview file to initialize a library that must run before your components render:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

initialize();

const preview: Preview = {
  // ...
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using, e.g. nextjs, nextjs-vite, react-vite, etc.

initialize();

const preview = definePreview({
  // ...
});

export default preview;
```

For example, with Vue, you can extend Storybook's application and register your library (e.g., [Fontawesome](https://github.com/FortAwesome/vue-fontawesome)). Or with Angular, add the package ([localize](https://angular.io/api/localize)) into your `polyfills.ts` and import it:

## Adding to \<head>

If you need to add extra elements to the `head` of the preview iframe, for instance, to load static stylesheets, font files, or similar, you can create a file called [`.storybook/preview-head.html`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) and add tags like this:

```html
// .storybook/preview-head.html

<link rel="preload" href="/fonts/my-font.woff2" />

<script src="https://use.typekit.net/xxxyyy.js"></script>
<script>
  try {
    Typekit.load();
  } catch (e) {}
</script>
```

Storybook will inject these tags into the _preview iframe_ where your components render, not the Storybook application UI.

However, it's also possible to modify the preview head HTML programmatically using a preset defined in the `main.js` file. Read the [presets documentation](https://storybook.js.org/docs/addons/writing-presets.md#ui-configuration) for more information.

## Adding to \<body>

Sometimes, you may need to add different tags to the `<body>`. Helpful for adding some custom content roots.

You can accomplish this by creating a file called `preview-body.html` inside your `.storybook` directory and adding tags like this:

```html
// .storybook/preview-body.html
<div id="custom-root"></div>
```

If using relative sizing in your project (like `rem` or `em`), you may update the base `font-size` by adding a `style` tag to `preview-body.html`:

```html
// .storybook/preview-body.html
<style>
  html {
    font-size: 15px;
  }
</style>
```

Storybook will inject these tags into the _preview iframe_ where your components render, not the Storybook application UI.

Just like how you have the ability to customize the preview `head` HTML tag, you can also follow the same steps to customize the preview `body` with a preset. To obtain more information on how to do this, refer to the [presets documentation](https://storybook.js.org/docs/addons/writing-presets.md#ui-configuration).
> Source: https://storybook.js.org/docs/configure/story-rendering
---

# Story layout

The `layout` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) allows you to configure how stories are positioned in Storybook's Canvas tab.

## Global layout

You can add the parameter to your [`./storybook/preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering), like so:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    layout: 'centered',
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    layout: 'centered',
  },
});
```

![Layout params centered story](../_assets/configure/layout-params-story-centered.png)

In the example above, Storybook will center all stories in the UI. `layout` accepts these options:

- `centered`: center the component horizontally and vertically in the Canvas
- `fullscreen`: allow the component to expand to the full width and height of the Canvas
- `padded`: _(default)_ Add extra padding around the component

## Component layout

You can also set it at a component level like so:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  // Sets the layout parameter component wide.
  parameters: {
    layout: 'centered',
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  // Sets the layout parameter component wide.
  parameters: {
    layout: 'centered',
  },
});
```

## Story layout

Or even apply it to specific stories like so:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const WithLayout: Story = {
  parameters: {
    layout: 'centered',
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const WithLayout = meta.story({
  parameters: {
    layout: 'centered',
  },
});
```
> Source: https://storybook.js.org/docs/configure/story-layout
---

# Features and behavior

To control the layout of Storybook’s UI you can use `addons.setConfig` in your `.storybook/manager.js`:

```ts
// .storybook/manager.ts

addons.setConfig({
  navSize: 300,
  bottomPanelHeight: 300,
  rightPanelWidth: 300,
  panelPosition: 'bottom',
  enableShortcuts: true,
  showToolbar: true,
  theme: undefined,
  selectedPanel: undefined,
  initialActive: 'sidebar',
  layoutCustomisations: {
    showSidebar(state: State, defaultValue: boolean) {
      return state.storyId === 'landing' ? false : defaultValue;
    },
    showToolbar(state: State, defaultValue: boolean) {
      return state.viewMode === 'docs' ? false : defaultValue;
    },
  },
  sidebar: {
    showRoots: false,
    collapsedRoots: ['other'],
  },
  toolbar: {
    title: { hidden: false },
    zoom: { hidden: false },
    eject: { hidden: false },
    copy: { hidden: false },
    fullscreen: { hidden: false },
  },
});
```

The following table details how to use the API values:

| Name                     | Type            | Description                                             | Example Value                                                                                  |
| ------------------------ | --------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **navSize**              | Number (pixels) | The size of the sidebar that shows a list of stories    | `300`                                                                                          |
| **bottomPanelHeight**    | Number (pixels) | The size of the addon panel when in the bottom position | `200`                                                                                          |
| **rightPanelWidth**      | Number (pixels) | The size of the addon panel when in the right position  | `200`                                                                                          |
| **panelPosition**        | String          | Where to show the addon panel                           | `'bottom'` or `'right'`                                                                        |
| **enableShortcuts**      | Boolean         | Enable/disable shortcuts                                | `true`                                                                                         |
| **showToolbar**          | Boolean         | Show/hide tool bar                                      | `true`                                                                                         |
| **theme**                | Object          | Storybook Theme, see next section                       | `undefined`                                                                                    |
| **selectedPanel**        | String          | Id to select an addon panel                             | `'storybook/actions/panel'`                                                                    |
| **initialActive**        | String          | Select the default active tab on Mobile                 | `'sidebar'` or `'canvas'` or `'addons'`                                                        |
| **layoutCustomisations** | Object          | Layout customisation options, see below                 | `{ showSidebar: ({ viewMode }, defaultValue) => viewMode === 'docs' ? false : defaultValue` }` |
| **sidebar**              | Object          | Sidebar options, see below                              | `{ showRoots: false }`                                                                         |
| **toolbar**              | Object          | Modify the tools in the toolbar using the addon id      | `{ fullscreen: { hidden: false } } `                                                           |

The following options are configurable under the `sidebar` namespace:

| Name               | Type     | Description                                                   | Example Value                                         |
| ------------------ | -------- | ------------------------------------------------------------- | ----------------------------------------------------- |
| **showRoots**      | Boolean  | Display the top-level nodes as a "root" in the sidebar        | `false`                                               |
| **collapsedRoots** | Array    | Set of root node IDs to visually collapse by default          | `['misc', 'other']`                                   |
| **renderLabel**    | Function | Create a custom label for tree nodes; must return a ReactNode | `(item, api) => <abbr title="...">{item.name}</abbr>` |

The following options are configurable under the `toolbar` namespace:

| Name     | Type   | Description                                                          | Example Value       |
| -------- | ------ | -------------------------------------------------------------------- | ------------------- |
| **[id]** | String | Toggle visibility for a specific toolbar item (e.g. `title`, `zoom`) | `{ hidden: false }` |

The following options are configurable under the `layoutCustomisations` namespace:

| Name            | Type     | Description                       | Example Value                                                                 |
| --------------- | -------- | --------------------------------- | ----------------------------------------------------------------------------- |
| **showSidebar** | Function | Toggle visibility for the sidebar | `({ storyId }, defaultValue) => storyId === 'landing' ? false : defaultValue` |
| **showToolbar** | Function | Toggle visibility for the toolbar | `({ viewMode }, defaultValue) => viewMode === 'docs' ? false : defaultValue`  |

The `showSidebar` and `showToolbar` functions let you hide parts of the UI that are essential to Storybook's functionality. If misused, they can make navigation impossible. When hiding the sidebar, ensure the displayed page provides an alternative means of navigation.

## Customize the UI

Storybook's UI is highly customizable. Its API and configuration options, available via the `showSidebar`, `showPanel` and `showToolbar` functions, allow you to control how the sidebar, addon panel and toolbar elements are displayed. Each function will enable you to include some default behavior and can be overridden to customize the UI to your needs.

### Override sidebar visibility

The sidebar, present on the left of the screen, contains the search function and navigation menu. Users may show or hide it with a keyboard shortcut. If you want to force the sidebar to be visible or hidden in certain places, you can define a `showSidebar` function in `layoutCustomisations`. Below are the available parameters passed to this function and an overview of how to use them.

| Name                     | Type    | Description                                                       | Example Value                                         |
| ------------------------ | ------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
| **path**                 | String  | Path to the page being displayed                                  | `'/story/components-button--default'`                 |
| **viewMode**             | String  | Whether the current page is a story or docs                       | `'docs'` or `'story'`                                 |
| **singleStory**          | Boolean | Whether the current page is the only story for a component        | `true` or `false`                                     |
| **storyId**              | String  | The id of the current story or docs page                          | `'blocks-unstyled--docs'`                             |
| **index**                | Object  | The index containing statically analysed metadata for every story | `{ 'blocks-unstyled--docs': { tags: ['autodocs'] } }` |
| **layout**               | Object  | The current layout state                                          | _see below_                                           |
| **layout.isFullscreen**  | Boolean | Whether the preview canvas is in fullscreen mode                  | `true` or `false`                                     |
| **layout.panelPosition** | String  | Whether the panel is shown below or on the side of the preview    | `'bottom'` or `'right'`                               |
| **layout.showNav**       | Boolean | The setting for whether the end user wants to see the sidebar     | `true` or `false`                                     |
| **layout.showPanel**     | Boolean | The setting for whether the end user wants to see the panel       | `true` or `false`                                     |
| **layout.showToolbar**   | Boolean | The setting for whether the end user wants to see the toolbar     | `true` or `false`                                     |

```ts
// ./storybook/manager.ts

addons.setConfig({
  layoutCustomisations: {
    // Hide the sidebar on the landing page, which has its own nav links to other pages.
    showSidebar(state: State, defaultValue: boolean) {
      if (state.storyId === 'landing' && state.viewMode === 'docs') {
        return false;
      }

      return defaultValue;
    },
  },
});
```

If you're hiding the sidebar through `showSidebar`, ensure the displayed page provides an alternative means of navigation.

### Configure the addon panel

When viewing a story, Storybook displays the addon panel on the bottom or right of the UI. The panel shows UIs for available addons (e.g., the [interactions panel](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests), [accessibility tests panel](https://storybook.js.org/docs/writing-tests/accessibility-testing.md) or [controls panel](https://storybook.js.org/docs/essentials/controls.md)). If you want to customize when the addon panel appears, you can use the `showPanel` function. Listed below are the available options and an overview of how to use them.

| Name                     | Type    | Description                                                       | Example Value                                         |
| ------------------------ | ------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
| **path**                 | String  | Path to the page being displayed                                  | `'/story/components-button--default'`                 |
| **viewMode**             | String  | Whether the current page is a story or docs                       | `'docs'` or `'story'`                                 |
| **singleStory**          | Boolean | Whether the current page is the only story for a component        | `true` or `false`                                     |
| **storyId**              | String  | The id of the current story or docs page                          | `'blocks-unstyled--docs'`                             |
| **index**                | Object  | The index containing statically analysed metadata for every story | `{ 'blocks-unstyled--docs': { tags: ['autodocs'] } }` |
| **layout**               | Object  | The current layout state                                          | _see below_                                           |
| **layout.isFullscreen**  | Boolean | Whether the preview canvas is in fullscreen mode                  | `true` or `false`                                     |
| **layout.panelPosition** | String  | Whether the panel is shown below or on the side of the preview    | `'bottom'` or `'right'`                               |
| **layout.showNav**       | Boolean | The setting for whether the end user wants to see the sidebar     | `true` or `false`                                     |
| **layout.showPanel**     | Boolean | The setting for whether the end user wants to see the panel       | `true` or `false`                                     |
| **layout.showToolbar**   | Boolean | The setting for whether the end user wants to see the toolbar     | `true` or `false`                                     |

```ts
// ./storybook/manager.ts

addons.setConfig({
  layoutCustomisations: {
    showPanel(state: State, defaultValue: boolean) {
      const tags = state.index?.[state.storyId]?.tags ?? [];

      // Hide the panel on stories designed to showcase multiple variants or usage examples.
      if (tags.includes('showcase') || tags.includes('kitchensink')) {
        return false;
      }

      return defaultValue;
    },
  },
});
```

### Configure the toolbar

By default, Storybook displays a toolbar at the top of the UI, allowing you to access menus from addons (e.g., [viewport](https://storybook.js.org/docs/essentials/viewport.md), [background](https://storybook.js.org/docs/essentials/backgrounds.md)), or custom defined [menus](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#global-types-and-the-toolbar-annotation). However, if you want to customize the toolbar's behavior, you can use the `showToolbar` function. Listed below are the available options and an overview of how to use them.

| Name                     | Type    | Description                                                       | Example Value                                         |
| ------------------------ | ------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
| **path**                 | String  | Path to the page being displayed                                  | `'/story/components-button--default'`                 |
| **viewMode**             | String  | Whether the current page is a story or docs                       | `'docs'` or `'story'`                                 |
| **singleStory**          | Boolean | Whether the current page is the only story for a component        | `true` or `false`                                     |
| **storyId**              | String  | The id of the current story or docs page                          | `'blocks-unstyled--docs'`                             |
| **index**                | Object  | The index containing statically analysed metadata for every story | `{ 'blocks-unstyled--docs': { tags: ['autodocs'] } }` |
| **layout**               | Object  | The current layout state                                          | _see below_                                           |
| **layout.isFullscreen**  | Boolean | Whether the preview canvas is in fullscreen mode                  | `true` or `false`                                     |
| **layout.panelPosition** | String  | Whether the panel is shown below or on the side of the preview    | `'bottom'` or `'right'`                               |
| **layout.showNav**       | Boolean | The setting for whether the end user wants to see the sidebar     | `true` or `false`                                     |
| **layout.showPanel**     | Boolean | The setting for whether the end user wants to see the panel       | `true` or `false`                                     |
| **layout.showToolbar**   | Boolean | The setting for whether the end user wants to see the toolbar     | `true` or `false`                                     |

```ts
// ./storybook/manager.ts

addons.setConfig({
  layoutCustomisations: {
    // Always hide the toolbar on docs pages, and respect user preferences elsewhere.
    showToolbar(state: State, defaultValue: boolean) {
      if (state.viewMode === 'docs') {
        return false;
      }

      return defaultValue;
    },
  },
});
```

## Change detection

Storybook can show status icons in the sidebar to highlight new and modified stories. See [change detection](https://storybook.js.org/docs/configure/user-interface/change-detection.md) for setup and details.

## Configuring through URL parameters

You can use URL parameters to configure some of the available features:

| Config option       | Query param  | Supported values                                                                             |
| ------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| **enableShortcuts** | `shortcuts`  | `false`                                                                                      |
| --- (fullscreen)    | `full`       | `true`, `false`                                                                              |
| --- (show sidebar)  | `nav`        | `true`, `false`                                                                              |
| --- (show panel)    | `panel`      | `false`, `'right'`, `'bottom'`                                                               |
| **selectedPanel**   | `addonPanel` | Any panel ID                                                                                 |
| **showTabs**        | `tabs`       | `true`                                                                                       |
| ---                 | `instrument` | `false`, `true`                                                                              |
| ---                 | `statuses`   | Semicolon-separated status values: `new`, `modified`, `related` (prefix with `!` to exclude) |
> Source: https://storybook.js.org/docs/configure/user-interface/features-and-behavior
---

# Change detection

Change detection is currently in [preview](https://storybook.js.org/docs/releases/features.md#preview).

The experience may change in future releases. We welcome feedback and contributions to help improve this feature.

During development, Storybook monitors your git working tree and the builder's module graph to identify which stories are related to your changes. A Review button at the top of the sidebar announces new and modified stories and lets you filter the tree to just those entries with one click. Status icons appear next to new stories and modified components so you can spot them at a glance.

![Sidebar showing review button and new story status icons](../../_assets/configure/change-detection-full.png)

## Requirements

Change detection is a **development-only** feature. It is active when running `storybook dev` and is not available in static builds (`storybook build`).

The following are required for change detection to work:

- **Git repository**: Storybook uses `git diff` to detect changed files.
- **Supported builder**: Storybook traces changed files through the builder's module import graph to identify all affected stories. Both Vite and webpack5 builders are supported. Other builders can gain support by implementing a change-detection adapter.

If change detection status indicators never appear in your sidebar, check that both requirements above are met and that the feature has not been [disabled](#configuration).

## Status indicators

When a change is detected, Storybook shows one of the following status icons next to the relevant stories in the sidebar:

| Icon                      | Status       | Definition                                                                            |
| ------------------------- | ------------ | ------------------------------------------------------------------------------------- |
| ✦&nbsp;Sparkle            | **new**      | The story file is untracked or newly added in git.                                    |
| ●&nbsp;Filled&nbsp;circle | **modified** | The story's own file, or a file it directly imports, was changed.                     |
| (no icon)                 | **related**  | A file further up the story's dependency chain was changed (a transitive dependency). |

When multiple statuses apply to the same story, the highest priority wins: **new** > **modified** > **related**.

Change detection statuses are displayed alongside [test statuses](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#storybook-ui) in the sidebar.

![Sidebar showing change detection and test status icons](../../_assets/configure/change-detection-dual-slot.png)

## Reviewing changes

A **Review** button appears between the search bar and the story tree whenever you have at least one new or modified story. The button toggles both the **new** and **modified** filters together with one click.

![Sidebar with active review button](../../_assets/configure/change-detection-review-button-active.png)

**Why are change detection filters off by default?**

The heuristics that Storybook uses to determine modified and related stories are designed to be fast and work without any configuration, but they aren't perfect. They can produce false positives (marking stories as modified or related when they aren't), which can be distracting if you have a large repository with many shared dependencies. For example, if you change a widely used utility function, Storybook might mark dozens of stories as related even if the change doesn't actually affect them. To avoid overwhelming you with status icons, Storybook keeps the change detection filters off by default, so you only see these statuses when you choose to review your changes.

## Filtering

For more granular control (e.g., to view only new stories) open the filter menu next to the search bar and check or uncheck the individual statuses.

![Filter menu showing change detection status options](../../_assets/configure/change-detection-filter-menu.png)

## Configuration

Change detection is enabled by default. To disable it, set [`features.changeDetection`](https://storybook.js.org/docs/api/main-config/main-config-features.md#changedetection) to `false` in your Storybook configuration:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    changeDetection: false,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    changeDetection: false,
  },
});
```

## Troubleshooting

If status icons don't appear in your sidebar, check the following:

- The dev server terminal log for messages prefixed with `Change detection:` — startup errors, unsupported builder warnings, and parse failures all surface there.
- That you are running `storybook dev` against a supported builder (Vite or webpack5).
- That your project is inside a git repository.
- That `features.changeDetection` is not set to `false` in your Storybook configuration.

### Workspace sibling packages not tracked in monorepos

In a monorepo, when a story imports a workspace sibling package (e.g., `@myorg/ui` declared as `"workspace:*"` in `package.json`), the dependency may not be tracked, meaning changes to that sibling won't trigger a story reload. There are two root causes:

**Built output missing at dev time.** Workspace packages typically point their `exports` or `main` fields to compiled output (`./dist/index.js`, `./esm/index.mjs`, etc.) that doesn't exist until the package is built. Storybook's resolver finds the symlink in `node_modules` but can't resolve the entry file, so it treats the import as untrackable. Even when the package has been built, its output directories are usually `.gitignore`d, meaning the resolved files are outside the set of watched source files and changes to them would never trigger a story reload.

**Per-package `tsconfig.json` blocking root paths.** Many monorepos define workspace path aliases in the root `tsconfig.json` (e.g., `"@myorg/*": ["./packages/@myorg/*/src"]`) so that bundlers resolve imports directly to source. If a package has its own `tsconfig.json` that doesn't extend root, Storybook's resolver finds that file first during its directory walk-up and never sees the root-level path mappings.

To ensure cross-workspace dependencies are tracked correctly, add `paths` entries to your root `tsconfig.json` pointing to the source directories of your workspace packages:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@myorg/*": ["./packages/@myorg/*/src"]
    }
  }
}
```

Storybook uses these mappings as a fallback when per-file resolution does not find the module.

### Many unrelated stories marked as related after a single change

If a change to one component (e.g., `Breadcrumb`) causes every story that imports from a shared package (e.g., `@myorg/ui`) to be marked as **related**, the package is likely using a barrel file — a single `index.ts` that re-exports everything.

Storybook performs **barrel-aware named import resolution**: when a story does `import { Button } from '@myorg/ui'`, Storybook traces through the barrel to find the actual source file (`Button.tsx`) and tracks that file instead of the barrel itself. This means a change to `Breadcrumb.tsx` will only mark stories that actually import `Breadcrumb` as related, not every story that imports from the barrel.

**Supported barrel patterns** (Storybook resolves these to the underlying source file):

- Direct named re-exports: `export { Button } from './Button'`
- Wildcard re-exports: `export * from './Button'`

**Patterns not fully supported** (Storybook falls back to tracking the barrel file itself):

- Two-step re-exports: `import { Button } from './Button'; export { Button }`
- Namespace re-exports: `export * as components from './components'`

If your barrel uses unsupported patterns, or if you need the most precise tracking possible, you can still import components from their direct source paths:

```ts
// Instead of the barrel import:

// Import directly from the component's source:

```

Whether this is practical depends on the library. Libraries that publish deep-import paths (or that you own and can restructure) support this; libraries that intentionally expose only a barrel do not.

### Debugging the dependency graph

Set the `STORYBOOK_CHANGE_DETECTION_DEBUG` environment variable to dump a JSON snapshot of the dependency graph when Storybook starts:

- `STORYBOOK_CHANGE_DETECTION_DEBUG=1` — writes `storybook-graph-debug.json` in the project root
- `STORYBOOK_CHANGE_DETECTION_DEBUG=/path/to/output.json` — writes to the specified path

The snapshot includes:

- All story-to-dependency edges tracked at startup
- The reverse index (which stories depend on each dep file, with BFS depth)
- A barrel resolution trace showing which named imports were resolved to which source files

This is useful for diagnosing why a specific story is or is not being marked as modified when you change a file.

## How it works

When you run `storybook dev`, Storybook builds its own dependency graph by parsing each story file (and its imports) with [oxc](https://oxc.rs/) and resolves module specifiers through the builder's resolve config. The builder ships a small change-detection adapter that forwards file-system events into Storybook so the graph stays current. A git diff provider watches your working tree for changes and runs `git diff` to identify modified or new files. Storybook then traces each changed file through the dependency graph to find all story files that depend on it — directly or transitively. Stories with the shortest import distance are marked **modified**; those at greater distance are marked **related**. New untracked files are marked **new**.
> Source: https://storybook.js.org/docs/configure/user-interface/change-detection
---

# Sidebar & URLS

Storybook’s sidebar lists all your stories grouped by component. When you have many components, you may also wish to group those components. To do so, you can add the `/` separator to the `title` of your CSF file, and Storybook will group the stories into groups based on common prefixes:

![Storybook sidebar anatomy](../../_assets/configure/sidebar-anatomy.png)

We recommend using a nesting scheme that mirrors the filesystem path of the components. For example, if you have a file `components/modals/Alert.js`, name the CSF file `components/modals/Alert.stories.js` and title it `Components/Modals/Alert`.

## Roots

By default, Storybook will treat your top-level nodes as “roots”. Roots are displayed in the UI as “sections” of the hierarchy. Lower level groups will show up as folders:

![Storybook sidebar story roots](../../_assets/configure/sidebar-roots.png)

If you’d prefer to show top-level nodes as folders rather than roots, you can set the `sidebar.showRoots` option to `false` in [`./storybook/manager.js`](https://storybook.js.org/docs/configure/user-interface/features-and-behavior.md):

```js
// ./storybook/manager.js

addons.setConfig({
  sidebar: {
    showRoots: false,
  },
});
```

## Permalink to stories

By default, Storybook generates an `id` for each story based on the component title and the story name. This `id` in particular is used in the URL for each story, and that URL can serve as a permalink (primarily when you [publish](https://storybook.js.org/docs/sharing/publish-storybook.md) your Storybook).

Consider the following story:

```ts
// FooBar.stories.ts|tsx — CSF 3
// Replace your-framework with the name of your framework

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Foo/Bar',
  component: Foo,
} satisfies Meta<typeof Foo>;

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

export const Baz: Story = {};
```

```ts
// FooBar.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Foo/Bar',
  component: Foo,
});

export const Baz = meta.story();
```

Storybook's ID-generation logic will give this the `id` `foo-bar--baz`, so the link would be `?path=/story/foo-bar--baz`.

It is possible to manually set the story's id, which is helpful if you want to rename stories without breaking permalinks. Suppose you want to change the position in the hierarchy to `OtherFoo/Bar` and the story name to `Moo`. Here's how to do that:

```ts
// FooBar.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'OtherFoo/Bar',
  component: Foo,
  id: 'Foo/Bar', // Or 'foo-bar' if you prefer
} satisfies Meta<typeof Foo>;

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

export const Baz: Story = {
  name: 'Insert name here',
};
```

```ts
// FooBar.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'OtherFoo/Bar',
  component: Foo,
  id: 'Foo/Bar', // Or 'foo-bar' if you prefer
});

export const Baz = meta.story({
  name: 'Insert name here',
});
```

Storybook will prioritize the `id` over the title for ID generation if provided and prioritize the `story.name` over the export key for display.

## CSF 3.0 auto-titles

Storybook 6.4 introduced [CSF 3.0](https://storybook.js.org/blog/component-story-format-3-0/) as an experimental feature, allowing you to write stories more compactly. Suppose you're already using this format to write your stories. In that case, you can omit the `title` element from the meta (or default export) and allow Storybook automatically infer it based on the file's physical location. For example, given the following configuration and story:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src'],
});
```

When Storybook loads, the story can show up in the sidebar as `components/My Component`.

Auto-titles work with explicit titling options like the component's `title` and the story's `name`:

```ts
// src/components/Button/Button.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  // Sets the name for the stories container
  title: 'components/Button',
  // The component name will be used if `title` is not set
  component: Button,
} satisfies Meta<typeof Button>;

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

// The story variable name will be used if `name` is not set
const Primary: Story = {
  // Sets the name for that particular story
  name: 'Primary',
  args: {
    label: 'Button',
  },
};
```

### Auto-title filename case

Starting with Storybook 6.5, story titles generated automatically no longer rely on Lodash's [startCase](https://lodash.com/docs/#startCase).
Instead, the file name casing is preserved, allowing additional control over the story title. For example, `components/My Component` will be defined as `components/MyComponent`.

If you need, you can revert to the previous pattern by adding the following configuration:

```js
// .storybook/manager.js

addons.setConfig({
  sidebar: {
    renderLabel: ({ name, type }) => (type === 'story' ? name : startCase(name)),
  },
});
```

### Auto-title redundant filenames

In addition to improvements to the story file name casing, a new heuristic was introduced, removing redundant names in case the filename has the same name as the directory name, or if it's called `index.stories.js|ts`. For example, before `components/MyComponent/MyComponent.stories.js` was defined as `Components/MyComponent/MyComponent` in the sidebar. Now it will be defined as `Components/MyComponent`.

If you need to preserve the naming scheme, you can add the `title` element to the meta (or default export). For example:

```ts
// components/MyComponent/MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  component: MyComponent,
  title: 'components/MyComponent/MyComponent',
} satisfies Meta<typeof MyComponent>;

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

export const Basic: Story = {
  args: {
    something: 'Something else',
  },
};
```

```ts
// components/MyComponent/MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  /* 👇 The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  component: MyComponent,
  title: 'components/MyComponent/MyComponent',
});

export const Basic = meta.story({
  args: {
    something: 'Something else',
  },
});
```

### Auto-title prefixes

Additionally, if you customize your Storybook to load your stories based on a [configuration object](https://storybook.js.org/docs/configure/index.md#with-a-configuration-object), including a `titlePrefix`, Storybook automatically prefixes all titles to matching stories. For example, assuming you have the following configuration:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    {
      directory: '../src',
      titlePrefix: 'Custom', // 👈 Configure the title prefix
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: [
    {
      directory: '../src',
      titlePrefix: 'Custom', // 👈 Configure the title prefix
    },
  ],
});
```

When Storybook generates the titles for all matching stories, they'll retain the `Custom` prefix.

### Story Indexers

[Story Indexers](https://storybook.js.org/docs/api/main-config/main-config-indexers.md) are a set of heuristics used by Storybook to crawl your filesystem based on a given glob pattern searching for matching stories, which is then used to generate an `index.json` (formerly `stories.json`) file responsible for populating the sidebar with the necessary information. By default, this heuristic will look for files that contain the following scheme `*.stories.@(js|jsx|mjs|ts|tsx)`.

You can provide your own indexer to include stories with a different naming convention, adjust the automatic title generation beyond a prefix, and many other use cases. For more information, see the [Story Indexers API reference](https://storybook.js.org/docs/api/main-config/main-config-indexers.md).

## Change detection

Storybook can show status icons in the sidebar to highlight new and modified stories. See [change detection](https://storybook.js.org/docs/configure/user-interface/change-detection.md) for setup and details.
> Source: https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls
---

# Theming

Storybook is theme-able using a lightweight theming API.

## Global theming

It's possible to theme Storybook globally.

Storybook includes a set of built-in themes that you can use to customize the appearance of your Storybook UI. The built-in themes are light, dark, and the "normal" theme that matches your preferred color scheme. Unless you specify otherwise, Storybook uses the normal theme by default.

As an example, you can tell Storybook to use the "dark" theme by modifying [`.storybook/manager.js`](https://storybook.js.org/docs/configure/user-interface/features-and-behavior.md):

```js
// .storybook/manager.js

addons.setConfig({
  theme: themes.dark,
});
```

When setting a theme, set a complete theme object. The theme is replaced, not combined.

## Theming docs

[Storybook Docs](https://storybook.js.org/docs/writing-docs.md) uses the same theme system as Storybook’s UI but is themed independently from the main UI. The default theme for Docs is always the "light" theme, regardless of the main UI theme.

Supposing you have a Storybook theme defined for the main UI in [`.storybook/manager.js`](https://storybook.js.org/docs/configure/user-interface/features-and-behavior.md):

```js
// .storybook/manager.js

addons.setConfig({
  theme: themes.dark,
});
```

Here's how you'd specify the same theme for docs in [`.storybook/preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      theme: themes.dark,
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      theme: themes.dark,
    },
  },
});
```

Continue to read if you want to learn how to create your theme.

## Create a theme quickstart

The easiest way to customize Storybook is to generate a new theme using the `create()` function from `storybook/theming`. This function includes shorthands for the most common theme variables. Here's how to use it:

Inside your `.storybook` directory, create a new file called `YourTheme.js` and add the following:

```js
// .storybook/YourTheme.js

export default create({
  base: 'light',
  brandTitle: 'My custom Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://storybook.js.org/images/placeholders/350x150.png',
  brandTarget: '_self',
});
```

If you're using `brandImage` to add your custom logo, you can use any of the most common image formats.

Above, we're creating a new theme that will:

- Use Storybook's `light` theme as a baseline.
- Replace Storybook's logo in the sidebar with our own (defined in the brandImage variable).
- Add custom branding information.
- Set the brand link to open in the same window (as opposed to a new one), via the `target` attribute.

Finally, we'll need to import the theme into Storybook. Create a new file called `manager.js` in your `.storybook` directory and add the following:

```js
// .storybook/manager.js

addons.setConfig({
  theme: yourTheme,
});
```

Now your custom theme will replace Storybook's default theme, and you'll see a similar set of changes in the UI.

![Storybook starter theme](../../_assets/configure/storybook-starter-custom-theme.png)

Let's take a look at a more complex example. Copy the code below and paste it in `.storybook/YourTheme.js`.

```js
// .storybook/YourTheme.js

export default create({
  base: 'light',
  // Typography
  fontBase: '"Open Sans", sans-serif',
  fontCode: 'monospace',
  brandTitle: 'My custom Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://storybook.js.org/images/placeholders/350x150.png',
  brandTarget: '_self',

  //
  colorPrimary: '#3A10E5',
  colorSecondary: '#585C6D',

  // UI
  appBg: '#ffffff',
  appContentBg: '#ffffff',
  appPreviewBg: '#ffffff',
  appBorderColor: '#585C6D',
  appBorderRadius: 4,

  // Text colors
  textColor: '#10162F',
  textInverseColor: '#ffffff',

  // Toolbar default and active colors
  barTextColor: '#9E9E9E',
  barSelectedColor: '#585C6D',
  barHoverColor: '#585C6D',
  barBg: '#ffffff',

  // Form colors
  inputBg: '#ffffff',
  inputBorder: '#10162F',
  inputTextColor: '#10162F',
  inputBorderRadius: 2,
});
```

Above, we're updating the theme with the following changes:

- A custom color palette (defined in the `app` and `color` variables).
- Custom fonts (defined in the `font` and `text` variables).

With the new changes introduced, the custom theme should yield a similar result.

![Storybook custom theme loaded](../../_assets/configure/storybook-custom-theme.png)

Many theme variables are optional, the <code>base</code> property is **NOT**.

The `storybook/theming` module is built using TypeScript, which should help create a valid theme for TypeScript users. The types are part of the package itself.

## CSS escape hatches

The Storybook theme API is narrow by design. If you want to have fine-grained control over the CSS, all UI and Docs components are tagged with class names to make this possible. **Use at your own risk** as this is an advanced feature.

To style these elements, insert style tags into:

- For Storybook’s UI, use `.storybook/manager-head.html`
- For Storybook Docs, use `.storybook/preview-head.html`

The same way as you can adjust your [preview’s head tag](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through `.storybook/manager-head.html`. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle.

## MDX component overrides

If you're using MDX for docs, there's one more level of "themability". MDX allows you to completely override the rendered components from Markdown using a `components` parameter. It's an advanced usage that we don't officially support in Storybook, but it's a powerful construct if you need it.

Here's how you might insert a custom code renderer for `code` blocks on the page, in [`.storybook/preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering):

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      components: {
        code: CodeBlock,
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      components: {
        code: CodeBlock,
      },
    },
  },
});
```

You can even override a Storybook block component.

Here's how you might insert a custom `` block:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      components: {
        Canvas: MyCanvas,
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      components: {
        Canvas: MyCanvas,
      },
    },
  },
});
```

## Addons and theme creation

Some addons require specific theme variables that a Storybook user must add. If you share your theme with the community, make sure to support the official API and other popular addons, so your users have a consistent experience.

For example, the popular Actions feature uses [react-inspector](https://github.com/storybookjs/react-inspector/blob/master/src/styles/themes/chromeLight.tsx), which has themes of its own. Supply additional theme variables to style it like so:

```js
addonActionsTheme: {
  ...chromeLight,
  BASE_FONT_FAMILY: typography.fonts.mono,
  BASE_BACKGROUND_COLOR: 'transparent',
}
```

## Using the theme for addon authors

Reuse the theme variables above for a native Storybook developer experience. The theming engine relies on [emotion](https://emotion.sh/), a CSS-in-JS library.

```js
// YourTheme.js

```

Use the theme variables in object notation:

```js
// MyComponent.js|jsx
const Component = styled.div(({ theme }) => ({
  background: theme.background.app,
  width: 0,
}));
```

Or with template literals:

```js
// MyComponent.js|jsx
const Component = styled.div`
  background: `${props => props.theme.background.app}`
  width: 0;
`;
```
> Source: https://storybook.js.org/docs/configure/user-interface/theming
---

# Storybook Addons

A key strength of Storybook is its extensibility. Use addons to extend and customize Storybook to fit your team’s development workflow.

Addons are integral to the way Storybook works. Many of Storybook's core features are implemented as addons, such as [`addon-docs`](https://storybook.js.org/addons/@storybook/addon-docs).

## Addon features

The most obvious thing addons affect in Storybook is the UI of Storybook itself. Within the UI the **toolbar** and **addons panel** are the two chief places addons will appear.

![Storybook addons locations](../../_assets/configure/addon-locations.png)

Addons can also hook into the rendering of your story in the preview pane via injecting their own [decorators](https://storybook.js.org/docs/writing-stories/decorators.md).

Finally, addons can affect the build setup of Storybook by injecting their own webpack configuration to allow the use of other tools in Storybook. Addons that do only this are often referred to as [presets](https://storybook.js.org/docs/addons/addon-types.md).

## Essential, core and community addons

There are many, many Storybook addons, but they can be roughly categorized into two areas:

- **Core** addons are developed by the core team. They are kept in sync with the development of Storybook itself and written in idiomatic ways as templates for other addons. They can be found within the [Storybook monorepo](https://github.com/storybookjs/storybook/tree/next/code/addons).
- **Community** addons are addons written by the massive Storybook community. They can be found on our [website](https://storybook.js.org/addons/), [GitHub](https://github.com/), and [npm](https://www.npmjs.com/).
> Source: https://storybook.js.org/docs/configure/user-interface/storybook-addons
---

# Environment variables

You can use environment variables in Storybook to change its behavior in different “modes”.
If you supply an environment variable prefixed with `STORYBOOK_`, it will be available in `process.env` when using Webpack, or `import.meta.env` when using the Vite builder:

```shell
STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook
```

Do not store any secrets (e.g., private API keys) or other types of sensitive information in your Storybook. Environment variables are embedded into the build, meaning anyone can view them by inspecting your files.

Then we can access these environment variables anywhere inside our preview JavaScript code like below:

```js
// node-env
console.log(process.env.STORYBOOK_THEME);
console.log(process.env.STORYBOOK_DATA_KEY);
```

```js
// vite-env
console.log(import.meta.env.STORYBOOK_THEME);
console.log(import.meta.env.STORYBOOK_DATA_KEY);
```

```js
// node-env
console.log(process.env.STORYBOOK_THEME);
console.log(process.env.STORYBOOK_DATA_KEY);
```

```js
// vite-env
console.log(import.meta.env.STORYBOOK_THEME);
console.log(import.meta.env.STORYBOOK_DATA_KEY);
```

You can also access these variables in your custom `<head>`/`<body>` using the substitution `%STORYBOOK_X%`, for example: `%STORYBOOK_THEME%` will become `red`.

If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly, for example: `<link rel="stylesheet" href="%STORYBOOK_STYLE_URL%" />`.

## Using .env files

You can also use `.env` files to change Storybook's behavior in different modes. For example, if you add a `.env` file to your project with the following:

```
STORYBOOK_DATA_KEY=12345
```

Then you can access this environment variable anywhere, even within your stories:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const ExampleStory: Story = {
  args: {
    propertyA: process.env.STORYBOOK_DATA_KEY,
  },
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const ExampleStory = meta.story({
  args: {
    propertyA: process.env.STORYBOOK_DATA_KEY,
  },
});
```

### With Vite

Out of the box, Storybook provides a [Vite builder](https://storybook.js.org/docs/builders/vite.md), which does not output Node.js globals like `process.env`. To access environment variables in Storybook (e.g., `STORYBOOK_`, `VITE_`), you can use `import.meta.env`. For example:

```tsx
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const ExampleStory: Story = {
  args: {
    propertyA: import.meta.env.STORYBOOK_DATA_KEY,
    propertyB: import.meta.env.VITE_CUSTOM_VAR,
  },
};
```

```tsx
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const ExampleStory = meta.story({
  args: {
    propertyA: import.meta.env.STORYBOOK_DATA_KEY,
    propertyB: import.meta.env.VITE_CUSTOM_VAR,
  },
});
```

You can also use specific files for specific modes. Add a `.env.development` or `.env.production` to apply different values to your environment variables.

You can also pass these environment variables when you are [building your Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md) with `build-storybook`.

Then they'll be hardcoded to the static version of your Storybook.

## Using Storybook configuration

Additionally, you can extend your Storybook configuration file (i.e., [`.storybook/main.js|.ts`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering)) and provide a configuration field that you can use to define specific variables (e.g., API URLs). For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  /*
   * 👇 The `config` argument contains all the other existing environment variables.
   * Either configured in an `.env` file or configured on the command line.
   */
  env: (config) => ({
    ...config,
    EXAMPLE_VAR: 'An environment variable configured in Storybook',
  }),
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  /*
   * 👇 The `config` argument contains all the other existing environment variables.
   * Either configured in an `.env` file or configured on the command line.
   */
  env: (config) => ({
    ...config,
    EXAMPLE_VAR: 'An environment variable configured in Storybook',
  }),
});
```

When Storybook loads, it will enable you to access them in your stories similar as you would do if you were working with an `env` file:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Basic: Story = {
  args: {
    exampleProp: process.env.EXAMPLE_VAR,
  },
};
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
});

export const Basic = meta.story({
  args: {
    exampleProp: process.env.EXAMPLE_VAR,
  },
});
```

## Using environment variables to choose the browser

Storybook allows you to choose the browser you want to preview your stories. Either through a `.env` file entry or directly in your `storybook` script.

The table below lists the available options:

| Browser  | Example              |
| -------- | -------------------- |
| Safari   | `BROWSER="safari"`   |
| Firefox  | `BROWSER="firefox"`  |
| Chromium | `BROWSER="chromium"` |

By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly.

## Troubleshooting

### Environment variables are not working

If you're trying to use framework-specific environment variables (e.g.,`VUE_APP_`), you may run into issues primarily due to the fact that Storybook and your framework may have specific configurations and may not be able to recognize and use those environment variables. If you run into a similar situation, you may need to adjust your framework configuration to make sure that it can recognize and use those environment variables. For example, if you're working with a Vite-based framework, you can extend the configuration file and enable the [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) option. Other frameworks may require a similar approach.
> Source: https://storybook.js.org/docs/configure/environment-variables
---

# Builders

Storybook, at its core, is powered by builders such as Webpack and Vite. These builders spin up a development environment, compile your code—Javascript, CSS, and MDX—into an executable bundle and update the browser in real-time.

![Storybook builder overview](../_assets/builders/storybook-builder-workflow.png)

## CLI basics

Before diving into setting up Storybook's builders, let's look at how the CLI configures them. When you initialize Storybook (via `npx storybook@latest init`), the CLI automatically detects which builder to use based on your application. For example, if you're working with Vite, it will install the Vite builder. If you're working with Webpack, it installs the Webpack 5 builder by default.

Additionally, you can also provide a flag to Storybook's CLI and specify the builder you want to use:

```shell
npx storybook@latest init --builder <webpack5 | vite>
```

## Manual setup

Storybook uses the Webpack 5 builder by default if you don't specify one. If you want to use a different builder in your application, these docs detail how you can set up Storybook's supported builders.

- [**Vite builder**](https://storybook.js.org/docs/builders/vite.md) for bundling your stories with Vite with near-instant HMR.
- [**Webpack**](https://storybook.js.org/docs/builders/webpack.md) for bundling your stories with Webpack with improved performance
- [**Rspack / Rsbuild**](https://github.com/rspack-contrib/storybook-rsbuild) for bundling your stories with blazing fast Rspack and Rsbuild.
> Source: https://storybook.js.org/docs/builders
---

# Vite

Storybook Vite builder bundles your components and stories with [Vite](https://vitejs.dev/), a fast ESM bundler.

- For applications built with Vite: it allows reusing the existing configuration in Storybook.
- For applications built with Webpack: it provides faster startup and refresh times, with the disadvantage that your component's execution environment differs from your application.

## Setup

If you ran `npx storybook@latest init` to include Storybook in your Vite application, the builder is already installed and configured for you. If you want, you can also opt into it manually.

Run the following command to install the builder.

```shell
npm install @storybook/builder-vite --save-dev
```

```shell
pnpm add --save-dev @storybook/builder-vite
```

```shell
yarn add --dev @storybook/builder-vite
```

Update your Storybook configuration (in `.storybook/main.js|ts`) to include the builder.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite, vue3-vite, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite', // 👈 The builder enabled here.
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite', // 👈 The builder enabled here.
  },
});
```

## Configuration

Out of the box, Storybook's Vite builder includes a set of configuration defaults for the supported frameworks, which are merged alongside your existing configuration file. For an optimal experience when using the Vite builder, we recommend applying any configuration directly inside Vite's configuration file (i.e., [`vite.config.js|ts`](https://vitejs.dev/config/)).

When Storybook loads, it automatically merges the configuration into its own. However, since different projects may have specific requirements, you may need to provide a custom configuration for Storybook. In such cases, you can modify your configuration file (`.storybook/main.js|ts`) and add the `viteFinal` configuration function as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite',
  },
  async viteFinal(config) {
    // Merge custom configuration into the default config
    const { mergeConfig } = await import('vite');

    return mergeConfig(config, {
      // Add dependencies to pre-optimization
      optimizeDeps: {
        include: ['storybook-dark-mode'],
      },
    });
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite',
  },
  async viteFinal(config) {
    // Merge custom configuration into the default config
    const { mergeConfig } = await import('vite');

    return mergeConfig(config, {
      // Add dependencies to pre-optimization
      optimizeDeps: {
        include: ['storybook-dark-mode'],
      },
    });
  },
});
```

The asynchronous function [`viteFinal`](https://storybook.js.org/docs/api/main-config/main-config-vite-final.md) receives a `config` object with the default builder configuration and returns the updated configuration.

### Environment-based configuration

If you need to customize the builder's configuration and apply specific options based on your environment, extend the `viteFinal` function as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config, { configType }) {
    const { mergeConfig } = await import('vite');

    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return mergeConfig(config, {
      // Your environment configuration here
    });
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config, { configType }) {
    const { mergeConfig } = await import('vite');

    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return mergeConfig(config, {
      // Your environment configuration here
    });
  },
});
```

### Override the default configuration

By default, the Vite builder in Storybook searches for the Vite configuration file in the root directory of your Storybook project. However, you can customize it to look for the configuration file in a different location. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-vite',
      options: {
        viteConfigPath: '../customVite.config.js',
      },
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-vite',
      options: {
        viteConfigPath: '../customVite.config.js',
      },
    },
  },
});
```

If you do not want Storybook to load the Vite configuration file automatically, you can use the `viteConfigPath` option to point to a non-existent file.

### TypeScript

If you need, you can also configure Storybook's Vite builder using TypeScript. Rename your `.storybook/main.js` to `.storybook/main.ts` and adjust it as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs-vite, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config, options) {
    // Add your configuration here
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config, options) {
    // Add your configuration here
    return config;
  },
});
```

---

## Troubleshooting

### Migrating from Webpack

Vite generally handles more use cases out of the box than Webpack. For example, loading styles just works for most projects. So, when migrating a Webpack-based project to Vite, you may find that you don't need all of your previous configuration.

We recommend starting with no Storybook-specific Vite configuration and only adding what you determine your project actually requires.

For reference, here is a Webpack configuration to handle loading graphql queries and its equivalent, using a plugin, in Vite:

```ts
// .storybook/main.ts — With Webpack (CSF 3)
// Replace your-framework with the framework you are using (e.g., react-webpack5, nextjs, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async webpackFinal(config) {
    config.module?.rules?.push({
      test: /\.(graphql|gql)$/,
      include: [path.resolve('./lib/emails')],
      exclude: /node_modules/,
      loader: 'graphql-tag/loader',
    });
    config.module?.rules?.push({
      test: /\.(graphql|gql)$/,
      include: [path.resolve('./lib/schema')],
      exclude: /node_modules/,
      loader: 'raw-loader',
    });

    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — With Vite (CSF 3)
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs-vite, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config) {
    return {
      ...config,
      plugins: [...(config.plugins ?? []), graphql()],
    };
  },
};

export default config;
```

```ts
// .storybook/main.ts — With Webpack (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., react-webpack5, nextjs)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async webpackFinal(config) {
    config.module?.rules?.push({
      test: /\.(graphql|gql)$/,
      include: [path.resolve('./lib/emails')],
      exclude: /node_modules/,
      loader: 'graphql-tag/loader',
    });
    config.module?.rules?.push({
      test: /\.(graphql|gql)$/,
      include: [path.resolve('./lib/schema')],
      exclude: /node_modules/,
      loader: 'raw-loader',
    });

    return config;
  },
});
```

```ts
// .storybook/main.ts — With Vite (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config) {
    return {
      ...config,
      plugins: [...(config.plugins ?? []), graphql()],
    };
  },
});
```

### Working directory not being detected

By default, the Vite builder enables Vite's [`server.fs.strict`](https://vitejs.dev/config/#server-fs-strict) option for increased security, defining the project's `root` to Storybook's configuration directory.
If you need to override it, you can use the `viteFinal` function and adjust it.

### ArgTypes are not generated automatically

Currently, [automatic argType inference](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference) is only available for React, Vue 3, and Svelte (JSDocs only). With React, the Vite builder defaults to `react-docgen`, a faster alternative to `react-docgen-typescript` for parsing React components. If you run into any issues, you can revert to `react-docgen-typescript` by updating your Storybook configuration file as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite',
  },
  typescript: {
    // Enables the `react-docgen-typescript` parser.
    // See https://storybook.js.org/docs/api/main-config/main-config-typescript for more information about this option.
    reactDocgen: 'react-docgen-typescript',
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite',
  },
  typescript: {
    // Enables the `react-docgen-typescript` parser.
    // See https://storybook.js.org/docs/api/main-config/main-config-typescript for more information about this option.
    reactDocgen: 'react-docgen-typescript',
  },
});
```

### Interaction tests not working as expected

If you are migrating from a Webpack-based project, such as [CRA](https://create-react-app.dev/), to Vite, and you are [interaction testing](https://storybook.js.org/docs/writing-tests/interaction-testing.md), you may run into a situation where your tests fail to execute notifying you that the `window` object is not defined. To resolve this issue, you can create a `preview-head.html` file in your Storybook configuration directory and include the following:

```html
// .storybook/preview-head.html
<script>
  window.global = window;
</script>
```

**Learn more about builders**

- Vite builder for bundling with Vite
- [Webpack builder](https://storybook.js.org/docs/builders/webpack.md) for bundling with Webpack
- [Builder API](https://storybook.js.org/docs/builders/builder-api.md) for building a Storybook builder
> Source: https://storybook.js.org/docs/builders/vite
---

# Webpack

Storybook Webpack builder is the default builder for Storybook. This builder enables you to create a seamless development and testing experience for your components and provides an efficient way to develop UI components in isolation allowing you to leverage your existing Webpack configuration with Storybook.

## Configure

By default, Storybook provides zero-config support for Webpack and automatically sets up a baseline configuration created to work with the most common use cases. However, you can extend your Storybook configuration file (i.e., `.storybook/main.js|ts`) and provide additional options to improve your Storybook's performance or customize it to your needs. Listed below are the available options and examples of how to use them.

| Option            | Description                                                                                                                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lazyCompilation` | Enables Webpack's experimental [`lazy compilation`](https://webpack.js.org/configuration/experiments/#experimentslazycompilation)<br />`core: { builder: { options: { lazyCompilation: true } } }` |
| `fsCache`         | Configures Webpack's filesystem [caching](https://webpack.js.org/configuration/cache/#cachetype) feature<br /> `core: { builder: { options: { fsCache: true } } }`                                 |

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-webpack5',
      options: {
        fsCache: true,
        lazyCompilation: true,
      },
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-webpack5',
      options: {
        fsCache: true,
        lazyCompilation: true,
      },
    },
  },
});
```

### Override the default configuration

Storybook's Webpack configuration is based on [Webpack 5](https://webpack.js.org/), allowing it to be extended to fit your project's needs. If you need to add a loader or a plugin, you can provide the `webpackFinal` configuration element in your [`.storybook/main.js|ts`](https://storybook.js.org/docs/configure/index.md#configure-your-storybook-project) file. The configuration element should export a function that receives the baseline configuration as the first argument and Storybook's options object as the second argument. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
});
```

When Storybook starts, it automatically merges the configuration into its own. However, when providing the `webpackFinal` configuration element, you're responsible for merging the configuration yourself. We recommend that you handle the changes to the `config` object responsibly, preserving both the `entry` and `output` properties.

#### Working with Webpack plugins

Another way to customize your Storybook configuration is to add a custom plugin or loader to help with code optimization, asset management, or other tasks. Nevertheless, since Storybook relies on the `HtmlWebpackPlugin` to generate the preview page, we recommend that you append the changes to the `config.plugins` array rather than overwriting it. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    config.plugins.push(/* ... */);
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, etc.

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    config.plugins.push(/* ... */);
    return config;
  },
});
```

Additionally, when working with Webpack loaders that don't explicitly include specific file extensions (i.e., via the `test` property), you should `exclude` the `.ejs` file extension for that loader.

### Import a custom Webpack configuration

If you already have an existing Webpack configuration file that you need to reuse with Storybook, you can import it and merge it into the default configuration. For example:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    return {
      ...config,
      module: { ...config.module, rules: [...config.module.rules, ...custom.module.rules] },
    };
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    return {
      ...config,
      module: { ...config.module, rules: [...config.module.rules, ...custom.module.rules] },
    };
  },
});
```

Projects scaffolded based on generators may require that you import their specific Webpack configuration files. We suggest reading your generator's documentation for more information.

### Debug Webpack configuration

If you intend to debug the Webpack configuration used by Storybook, you can use the Storybook CLI to help you. If you're running in [development mode](https://storybook.js.org/docs/api/cli-options.md#dev), you can use the following command:

```shell
npm run storybook -- --debug-webpack
```

```shell
yarn storybook --debug-webpack
```

Additionally, if you're generating a [static build](https://storybook.js.org/docs/api/cli-options.md#build) of your Storybook, you can use the following command:

```shell
npm run build-storybook -- --debug-webpack
```

```shell
yarn build-storybook --debug-webpack
```

## Compiler support

Storybook takes a compiler-agnostic approach to bundling. This allows you to bring your own application bundler (e.g., [Babel](https://babeljs.io/), [SWC](https://swc.rs/)) and ensures compatibility within the vast ecosystem of Webpack 5-based projects.

### SWC

If your project is built using [SWC](https://swc.rs/), use the [`@storybook/addon-webpack5-compiler-swc`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-swc) addon. This addon increases ecosystem compatibility with Webpack 5 projects while maintaining high performance. Run the following command to set up the addon automatically:

```sh
npx storybook@latest add @storybook/addon-webpack5-compiler-swc
```

```sh
pnpm dlx storybook@latest add @storybook/addon-webpack5-compiler-swc
```

```sh
yarn dlx storybook@latest add @storybook/addon-webpack5-compiler-swc
```

Additional options can be provided to customize the SWC configuration. See the [SWC API documentation](https://storybook.js.org/docs/api/main-config/main-config-swc.md) for more information.

When enabled, this addon adjusts the Webpack configuration to use the [`swc-loader`](https://swc.rs/docs/usage/swc-loader) for JavaScript and TypeScript files. Additionally, it will detect and use your project's SWC configuration.

### Babel

If you're working with a project that relies on Babel's tooling to provide support for specific features, including TypeScript or other modern JavaScript features, you can use the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon to allow you to include them in your Storybook to ensure compatibility with your project. Run the following command to set up the addon automatically:

```sh
npx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

```sh
pnpm dlx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

```sh
yarn dlx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

Additional options can be provided to customize the Babel configuration. See the [`babel` API documentation](https://storybook.js.org/docs/api/main-config/main-config-babel.md) for more information, or if you're working on an addon, the [`babelDefault` documentation](https://storybook.js.org/docs/api/main-config/main-config-babel-default.md) for more information.

When enabled, the addon will adjust the Webpack configuration to use the [`babel-loader`](https://webpack.js.org/loaders/babel-loader/) as the default loader for JavaScript and TypeScript files. Additionally, it will detect and use your project's Babel configuration.

## Troubleshooting

### TypeScript modules are not resolved within Storybook

Storybook's default Webpack configuration provides support for most project setups without the need for any additional configuration. Nevertheless, depending on your project configuration, or the framework of choice, you may run into issues with TypeScript modules not being resolved within Storybook when aliased from your [`tsconfig` file](https://www.typescriptlang.org/tsconfig). If you encounter this issue, you can use [`tsconfig-paths-webpack-plugin`](https://github.com/dividab/tsconfig-paths-webpack-plugin#tsconfig-paths-webpack-plugin) while [extending Storybook's Webpack config](#override-the-default-configuration) as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.plugins = [
        ...(config.resolve.plugins || []),
        new TsconfigPathsPlugin({
          extensions: config.resolve.extensions,
        }),
      ];
    }
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.plugins = [
        ...(config.resolve.plugins || []),
        new TsconfigPathsPlugin({
          extensions: config.resolve.extensions,
        }),
      ];
    }
    return config;
  },
});
```

However, if you're working with a framework that provides a default aliasing configuration (e.g., Next.js, Nuxt) and you want to configure Storybook to use the same aliases, you may not need to install any additional packages. Instead, you can extend the default configuration of Storybook to use the same aliases provided by the framework. For example, to set up an alias for the `@` import path, you can add the following to your `.storybook/main.js|ts` file:

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@': path.resolve(process.cwd(), 'src'),
      };
    }
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, etc.

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@': path.resolve(process.cwd(), 'src'),
      };
    }
    return config;
  },
});
```

### Pre-bundled assets do not show in the Storybook UI

As Storybook relies on [esbuild](https://esbuild.github.io/) to build its internal manager, support for bundling assets with the `managerWebpack` will no longer have an impact on the Storybook UI. We recommend removing existing `managerWebpack` configuration elements from your Storybook configuration file and bundling assets other than images or CSS into JavaScript beforehand.

### Storybook doesn't run with Webpack 4

Support for Webpack 4 has been removed and is no longer being maintained. If you're upgrading your Storybook, it will automatically use Webpack 5 and attempt to migrate your configuration. However, if you're working with a custom Webpack configuration, you may need to update it to work with Webpack 5. The migration process is necessary to ensure that your project runs smoothly with the latest version of Storybook. You can follow the instructions provided on the Webpack [website](https://webpack.js.org/migrate/5/) to update your configuration.

**Learn more about builders**

- [Vite builder](https://storybook.js.org/docs/builders/vite.md) for bundling with Vite
- Webpack builder for bundling with Webpack
- [Builder API](https://storybook.js.org/docs/builders/builder-api.md) for building a Storybook builder
> Source: https://storybook.js.org/docs/builders/webpack
---

# Builder API

Storybook is architected to support multiple builders, including [Webpack](https://webpack.js.org/), [Vite](https://vitejs.dev/), and [ESBuild](https://esbuild.github.io/). The builder API is the set of interfaces you can use to add a new builder to Storybook.

![Storybook builders](../_assets/builders/storybook-builders.png)

## How do builders work?

In Storybook, a builder is responsible for compiling your components and stories into JS bundles that run in the browser. A builder also provides a development server for interactive development and a production mode for optimized bundles.

To opt into a builder, the user must add it as a dependency and then edit their configuration file (`.storybook/main.js`) to enable it. For example, with the Vite builder:

```shell
npm install @storybook/builder-vite --save-dev
```

```shell
pnpm add --save-dev @storybook/builder-vite
```

```shell
yarn add --dev @storybook/builder-vite
```

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite, vue3-vite, etc.)

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite', // 👈 The builder enabled here.
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite', // 👈 The builder enabled here.
  },
});
```

## Builder API

In Storybook, every builder must implement the following [API](https://github.com/storybookjs/storybook/blob/next/code/core/src/types/modules/core-common.ts#L255-L275), exposing the following configuration options and entry points:

```ts
// core-common.ts
export interface Builder<Config, BuilderStats extends Stats = Stats> {
  getConfig: (options: Options) => Promise<Config>;
  start: (args: {
    options: Options;
    startTime: ReturnType<typeof process.hrtime>;
    router: ServerApp;
    server: HttpServer;
    channel: ServerChannel;
  }) => Promise<void | {
    stats?: BuilderStats;
    totalTime: ReturnType<typeof process.hrtime>;
    bail: (e?: Error) => Promise<void>;
  }>;
  build: (arg: {
    options: Options;
    startTime: ReturnType<typeof process.hrtime>;
  }) => Promise<void | BuilderStats>;
  bail: (e?: Error) => Promise<void>;
  corePresets?: string[];
  overridePresets?: string[];
}
```

In development mode, the `start` API call is responsible for initializing the development server to monitor the file system for changes (for example, components and stories) then execute a hot module reload in the browser.
It also provides a **bail** function to allow the running process to end gracefully, either via user input or error.

In production, the `build` API call is responsible for generating a static Storybook build, storing it by default in the `storybook-static` directory if no additional configuration is provided. The generated output should contain everything the user needs to view its Storybook by opening either the `index.html` or `iframe.html` in a browser with no other processes running.

## Implementation

Under the hood, a builder is responsible for serving/building the preview `iframe`, which has its own set of requirements. To fully support Storybook, including the [essential features](https://storybook.js.org/docs/writing-stories.md) that ship with Storybook, it must consider the following.

### Import stories

The `stories` configuration field enables story loading in Storybook. It defines an array of file globs containing the physical location of the component's stories. The builder must be able to load those files and monitor them for changes and update the UI accordingly.

### Provide configuration options

By default, Storybook's configuration is handled in a dedicated file (`storybook/main.js|ts`), giving the user the option to customize it to suit its needs. The builder should also provide its own configuration support through additional fields or some other builder-appropriate mechanism. For example:

```ts
// vite-server.ts

export async function createViteServer(options: ExtendedOptions, devServer: Server) {
  const { port, presets } = options;

  // Defines the baseline config.
  const baseConfig = await commonConfig(options, 'development');
  const defaultConfig = {
    ...baseConfig,
    server: {
      middlewareMode: true,
      hmr: {
        port,
        server: devServer,
      },
      fs: {
        strict: true,
      },
    },
    optimizeDeps: await getOptimizeDeps(baseConfig, options),
  };

  const finalConfig = await presets.apply('viteFinal', defaultConfig, options);

  const envsRaw = await presets.apply<Promise<EnvsRaw>>('env');

  // Remainder implementation
}
```

### Handle preview.js exports

The [`preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) configuration file allows users to control how the story renders in the UI. This is provided via the [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) named export. When Storybook starts, it converts these named exports into internal API calls via virtual module entry, for example, `addDecorator()`. The builder must also provide a similar implementation. For example:

```ts

export async function generateIframeScriptCode(options: ExtendedOptions) {
  const { presets, frameworkPath, framework } = options;
  const frameworkImportPath = frameworkPath || `@storybook/${framework}`;

  const presetEntries = await presets.apply('config', [], options);
  const configEntries = [...presetEntries].filter(Boolean);

  const absoluteFilesToImport = (files: string[], name: string) =>
    files
      .map((el, i) => `import ${name ? `* as ${name}_${i} from ` : ''}'${transformAbsPath(el)}'`)
      .join('\n');

  const importArray = (name: string, length: number) =>
    new Array(length).fill(0).map((_, i) => `${name}_${i}`);

  const code = `
    // Ensure that the client API is initialized by the framework before any other iframe code
    // is loaded. That way our client-apis can assume the existence of the API+store
    import { configure } from '${frameworkImportPath}';

    import {
      addDecorator,
      addParameters,
      addArgTypesEnhancer,
      addArgsEnhancer,
      setGlobalRender
    } from 'storybook/preview-api';
    import { logger } from 'storybook/internal/client-logger';
    ${absoluteFilesToImport(configEntries, 'config')}
    import * as preview from '${virtualPreviewFile}';
    import { configStories } from '${virtualStoriesFile}';

    const configs = [${importArray('config', configEntries.length)
      .concat('preview.default')
      .join(',')}].filter(Boolean)

    configs.forEach(config => {
      Object.keys(config).forEach((key) => {
        const value = config[key];
        switch (key) {
          case 'args':
          case 'argTypes': {
            return logger.warn('Invalid args/argTypes in config, ignoring.', JSON.stringify(value));
          }
          case 'decorators': {
            return value.forEach((decorator) => addDecorator(decorator, false));
          }
          case 'parameters': {
            return addParameters({ ...value }, false);
          }
          case 'render': {
            return setGlobalRender(value)
          }
          case 'globals':
          case 'globalTypes': {
            const v = {};
            v[key] = value;
            return addParameters(v, false);
          }
          case 'decorateStory':
          case 'renderToCanvas': {
            return null;
          }
          default: {
            // eslint-disable-next-line prefer-template
            return console.log(key + ' was not supported :( !');
          }
        }
      });
    })
    configStories(configure);
    `.trim();
  return code;
}
```

### MDX support

[Storybook's Docs](https://storybook.js.org/docs/writing-docs.md) includes the ability to author stories/documentation in MDX using a Webpack loader. The builder must also know how to interpret MDX and invoke Storybook's special extensions. For example:

```ts
// mdx-plugin.ts

export function mdxPlugin() {
  return mdx((filename) => {
    const compilers = [];

    if (filename.endsWith('stories.mdx') || filename.endsWith('story.mdx')) {
      compilers.push(createCompiler({}));
    }
    return {
      compilers,
    };
  });
}
```

### Generate source code snippets

Storybook annotates components and stories with additional metadata related to their inputs to automatically generate interactive controls and documentation. Currently, this is provided via Webpack loaders/plugins. The builder must re-implement this to support those features.

### Generate a static build

One of Storybook's core features it's the ability to generate a static build that can be [published](https://storybook.js.org/docs/sharing/publish-storybook.md) to a web hosting service. The builder must also be able to provide a similar mechanism. For example:

```ts
// build.ts

export async function build(options: ExtendedOptions) {
  const { presets } = options;

  const baseConfig = await commonConfig(options, 'build');
  const config = {
    ...baseConfig,
    build: {
      outDir: options.outputDir,
      emptyOutDir: false,
      sourcemap: true,
    },
  };

  const finalConfig = await presets.apply('viteFinal', config, options);

  const envsRaw = await presets.apply<Promise<EnvsRaw>>('env');
  // Stringify env variables after getting `envPrefix` from the final config
  const envs = stringifyProcessEnvs(envsRaw, finalConfig.envPrefix);
  // Update `define`
  finalConfig.define = {
    ...finalConfig.define,
    ...envs,
  };

  await viteBuild(finalConfig);
}
```

### Development server integration

By default, when Storybook starts in development mode, it relies on its internal development server. The builder needs to be able to integrate with it. For example:

```ts
// server.ts

export async function createViteServer(options: ExtendedOptions, devServer: Server) {
  const { port } = options;
  // Remainder server configuration

  // Creates the server.
  return createServer({
    // The server configuration goes here
    server: {
      middlewareMode: true,
      hmr: {
        port,
        server: devServer,
      },
    },
  });
}
```

### Shutdown the development server

The builder must provide a way to stop the development server once the process terminates; this can be via user input or error. For example:

```ts
// index.ts

let server: ViteDevServer;
export async function bail(): Promise<void> {
  return server?.close();
}

export const start: ViteBuilder['start'] = async ({ options, server: devServer }) => {
  // Remainder implementation goes here
  server = await createViteServer(options as ExtendedOptions, devServer);

  return {
    bail,
    totalTime: process.hrtime(startTime),
  };
};
```

### HMR support

While running in development mode, the builder's development server must be able to reload the page once a change happens, either in a story, component, or helper function.

### More information

This area is under rapid development, and the associated documentation is still in progress and subject to change. If you are interested in creating a builder, you can learn more about implementing a builder in Storybook by checking the source code for [Vite](https://github.com/storybookjs/storybook/tree/next/code/builders/builder-vite), [Webpack](https://github.com/storybookjs/storybook/tree/next/code/builders/builder-webpack5), or Modern Web's [dev-server-storybook](https://github.com/modernweb-dev/web/blob/master/packages/dev-server-storybook/src/serve/storybookPlugin.ts). When you're ready, open an [RFC](https://storybook.js.org/docs/contribute/RFC.md) to discuss your proposal with the Storybook community and maintainers.

**Learn more about builders**

- [Vite builder](https://storybook.js.org/docs/builders/vite.md) for bundling with Vite
- [Webpack builder](https://storybook.js.org/docs/builders/webpack.md) for bundling with Webpack
- Builder API for building a Storybook builder
> Source: https://storybook.js.org/docs/builders/builder-api
---

# API references

An overview of all available API references for Storybook.

## Configuration

  <thead>
    
      Name
      Description
    
  </thead>

  <tbody>
    
      <code>main.js|ts</code>

      
        Storybook's primary configuration file, which specifies your Storybook project's behavior,
        including the location of your stories, the addons you use, feature flags and other
        project-specific settings.
      
    

    
      <code>preview.js|jsx|ts|tsx</code>

      
        This configuration file controls the way stories are rendered. You can also use it to run
        code that applies to all stories.
      
    

    
      <code>manager.js|ts</code>

      
        This configuration file controls the behavior of Storybook's UI, the manager.
      
    

    
      CLI

      
        Storybook is a CLI tool. You can start Storybook in development mode or build a static
        version of your Storybook.
      
    

  </tbody>

## Stories

  <thead>
    
      Name
      Description
    
  </thead>

  <tbody>
    
      CSF

      
        Component Story Format (CSF) is the API for writing stories. It's an
        open standard based on ES6 modules that
        is portable beyond Storybook.
      
    

    
      ArgTypes

      
        ArgTypes specify the behavior of <a href="./writing-stories/args">args</a>. By specifying
        the type of an arg, you constrain the values that it can accept and provide information
        about args that are not explicitly set.
      
    

    
      Parameters

      
        Parameters are static metadata used to configure your <a href="./get-started/whats-a-story">stories</a> <a href="./addons">addons</a> in Storybook. They are specified at the story, meta (component), project (global) levels.
      
    

  </tbody>

## Docs

  <thead>
    
      Name
      Description
    
  </thead>

  <tbody>
    
      Doc blocks

      
        Storybook offers several doc blocks to help document your components and other aspects of
        your project.
      
    

  </tbody>
> Source: https://storybook.js.org/docs/api
---

# Main configuration

The main configuration defines a Storybook project's behavior, including the location of stories, addons to use, feature flags, and other project-specific settings.

## The main configuration file: `main.js` or `main.ts`

This file must be valid ESM. In other words, it must use `import` instead of `require`, and neither `__dirname` nor `__filename` are available.

This configuration is defined in `.storybook/main.js|ts`, which is located relative to the root of your project.

A typical Storybook configuration file looks like this:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-docs'],
  staticDirs: ['../public'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-docs'],
  staticDirs: ['../public'],
});
```

## config

An object to configure Storybook containing the following properties:

- [`framework`](https://storybook.js.org/docs/api/main-config/main-config-framework.md) (Required)
- [`stories`](https://storybook.js.org/docs/api/main-config/main-config-stories.md) (Required)
- [`addons`](https://storybook.js.org/docs/api/main-config/main-config-addons.md)
- [`babel`](https://storybook.js.org/docs/api/main-config/main-config-babel.md)
- [`babelDefault`](https://storybook.js.org/docs/api/main-config/main-config-babel-default.md)
- [`build`](https://storybook.js.org/docs/api/main-config/main-config-build.md)
- [`core`](https://storybook.js.org/docs/api/main-config/main-config-core.md)
- [`docs`](https://storybook.js.org/docs/api/main-config/main-config-docs.md)
- [`env`](https://storybook.js.org/docs/api/main-config/main-config-env.md)
- [`features`](https://storybook.js.org/docs/api/main-config/main-config-features.md)
- [`indexers`](https://storybook.js.org/docs/api/main-config/main-config-indexers.md) (⚠️ Experimental)
- [`logLevel`](https://storybook.js.org/docs/api/main-config/main-config-log-level.md)
- [`managerHead`](https://storybook.js.org/docs/api/main-config/main-config-manager-head.md)
- [`previewAnnotations`](https://storybook.js.org/docs/api/main-config/main-config-preview-annotations.md)
- [`previewBody`](https://storybook.js.org/docs/api/main-config/main-config-preview-body.md)
- [`previewHead`](https://storybook.js.org/docs/api/main-config/main-config-preview-head.md)
- [`refs`](https://storybook.js.org/docs/api/main-config/main-config-refs.md)
- [`staticDirs`](https://storybook.js.org/docs/api/main-config/main-config-static-dirs.md)
- [`swc`](https://storybook.js.org/docs/api/main-config/main-config-swc.md)
- [`tags`](https://storybook.js.org/docs/api/main-config/main-config-tags.md)
- [`typescript`](https://storybook.js.org/docs/api/main-config/main-config-typescript.md)
- [`viteFinal`](https://storybook.js.org/docs/api/main-config/main-config-vite-final.md)
- [`webpackFinal`](https://storybook.js.org/docs/api/main-config/main-config-webpack-final.md)
> Source: https://storybook.js.org/docs/api/main-config/main-config
---

# framework

(**Required**)

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `FrameworkName | { name: FrameworkName; options?: FrameworkOptions }`

Configures Storybook based on a set of [framework-specific](https://storybook.js.org/docs/configure/integration/frameworks.md) settings.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const config: StorybookConfig = {
  framework: {
    name: '@storybook/your-framework',
    options: {
      legacyRootApi: true,
    },
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: {
    name: '@storybook/your-framework',
    options: {
      legacyRootApi: true,
    },
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
});
```

## `name`

Type: `string`

For available frameworks and their options, see their respective [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks).

## `options`

Type: `Record<string, any>`

While many options are specific to a framework, there are some options that are shared across some frameworks, e.g. those that configure Storybook's [builder](https://storybook.js.org/docs/api/main-config/main-config-core.md#builder).

### `options.builder`

Type: `Record<string, any>`

Configures Storybook's builder, [Vite](https://storybook.js.org/docs/builders/vite.md) or [Webpack](https://storybook.js.org/docs/builders/webpack.md).
> Source: https://storybook.js.org/docs/api/main-config/main-config-framework
---

# stories

(**Required**)

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type:

```ts
| (string | StoriesSpecifier)[]
| async (list: (string | StoriesSpecifier)[]) => (string | StoriesSpecifier)[]
```

Configures Storybook to load stories from the specified locations. The intention is for you to colocate a story file along with the component it documents:

```
•
└── components
    ├── Button.ts
    └── Button.stories.ts
```

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
});
```

If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features).

Keep in mind that some addons may assume Storybook's default naming convention.

## With an array of globs

Storybook will load stories from your project as found by this array of globs (pattern matching strings).

Stories are loaded in the order they are defined in the array. This allows you to control the order in which stories are displayed in the sidebar:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx', // 👈 These will display first in the sidebar
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)', // 👈 Followed by these
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx', // 👈 These will display first in the sidebar
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)', // 👈 Followed by these
  ],
});
```

## With a configuration object

Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. This object is of the type `StoriesSpecifier`, defined below.

For example, if you wanted to load your stories from a `packages/components` directory, you could adjust your `stories` configuration field into the following:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../packages/components',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
      // 👇 Used when generating automatic titles for your stories
      titlePrefix: 'MyComponents',
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../packages/components',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
      // 👇 Used when generating automatic titles for your stories
      titlePrefix: 'MyComponents',
    },
  ],
});
```

When Storybook starts, it will look for any file containing the `stories` extension inside the `packages/components` directory and generate the titles for your stories.

### `StoriesSpecifier`

Type:

```ts
{
  directory: string;
  files?: string;
  titlePrefix?: string;
}
```

#### `StoriesSpecifier.directory`

(**Required**)

Type: `string`

Where to start looking for story files, relative to the root of your project.

#### `StoriesSpecifier.files`

Type: `string`

Default: `'**/*.@(mdx|stories.@(js|jsx|mjs|ts|tsx))'`

A glob, relative to `StoriesSpecifier.directory` (with no leading `./`), that matches the filenames to load.

#### `StoriesSpecifier.titlePrefix`

Type: `string`

Default: `''`

When [auto-titling](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#csf-30-auto-titles), prefix used when generating the title for your stories.

## With a custom implementation

Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability.

You can also adjust your Storybook configuration and implement custom logic to load your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve. In that case, you could adjust your configuration as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

async function findStories(): Promise<StoriesEntry[]> {
  // your custom logic returns a list of files
}

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: async (list: StoriesEntry[]) => [
    ...list,
    // 👇 Add your found stories to the existing list of story files
    ...(await findStories()),
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

async function findStories(): Promise<StoriesEntry[]> {
  // your custom logic returns a list of files
}

export default defineMain({
  framework: '@storybook/your-framework',
  stories: async (list: StoriesEntry[]) => [
    ...list,
    // 👇 Add your found stories to the existing list of story files
    ...(await findStories()),
  ],
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-stories
---

# addons

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(string | { name: string; options?: AddonOptions })[]`

Registers the [addons](https://storybook.js.org/docs/addons/install-addons.md) loaded by Storybook.

For each addon's available options, see their respective [documentation](https://storybook.js.org/integrations).

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-docs',
    {
      name: '@storybook/addon-styling-webpack',
      options: {
        rules: [
          {
            test: /\.css$/,
            use: [
              'style-loader',
              'css-loader',
              {
                loader: 'postcss-loader',
                options: {
                  implementation: fileURLToPath(import.meta.resolve('postcss')),
                },
              },
            ],
          },
        ],
      },
    },
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-docs',
    {
      name: '@storybook/addon-styling-webpack',
      options: {
        rules: [
          {
            test: /\.css$/,
            use: [
              'style-loader',
              'css-loader',
              {
                loader: 'postcss-loader',
                options: {
                  implementation: fileURLToPath(import.meta.resolve('postcss')),
                },
              },
            ],
          },
        ],
      },
    },
  ],
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-addons
---

# babel

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise<Babel.Config>`

Customize Storybook's [Babel](https://babeljs.io/) setup.

[Addon authors](https://storybook.js.org/docs/addons/writing-presets.md#babel) should use [`babelDefault`](https://storybook.js.org/docs/api/main-config/main-config-babel-default.md) instead, which is applied to the preview config before any user presets have been applied.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async babel(config, { configType }) {
    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async babel(config, { configType }) {
    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return config;
  },
});
```

## `Babel.Config`

The options provided by [Babel](https://babeljs.io/docs/options) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon.

If you have an existing Babel configuration file (e.g., `.babelrc`), it will be automatically detected and used by Storybook without any additional configuration required.

## `Options`

Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }`

There are other options that are difficult to document here. Please introspect the type definition for more information.
> Source: https://storybook.js.org/docs/api/main-config/main-config-babel
---

# babelDefault

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise<Babel.Config>`

`babelDefault` allows customization of Storybook's [Babel](https://babeljs.io/) setup. It is applied to the preview config before any user presets have been applied, which makes it useful and recommended for [addon authors](https://storybook.js.org/docs/addons/writing-presets.md#babel) so that the end user's [`babel`](https://storybook.js.org/docs/api/main-config/main-config-babel.md) setup can override it.

To adjust your Storybook's Babel setup directly—not via an addon—use [`babel`](https://storybook.js.org/docs/api/main-config/main-config-babel.md) instead.

```ts

export function babelDefault(config: TransformOptions) {
  return {
    plugins: [[import.meta.resolve('@babel/plugin-transform-react-jsx'), {}, 'preset']],
  };
}
```

## `Babel.Config`

The options provided by [Babel](https://babeljs.io/docs/options) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon.

## `Options`

Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }`

There are other options that are difficult to document here. Please introspect the type definition for more information.
> Source: https://storybook.js.org/docs/api/main-config/main-config-babel-default
---

# build

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `TestBuildConfig`

Provides configuration options to optimize Storybook's production build output.

## `test`

Type: `TestBuildFlags`

```ts
{
  disableBlocks?: boolean;
  disabledAddons?: string[];
  disableMDXEntries?: boolean;
  disableAutoDocs?: boolean;
  disableDocgen?: boolean;
  disableSourcemaps?: boolean;
  disableTreeShaking?: boolean;

}
```

Configures Storybook's production builds for performance testing purposes by disabling certain features from the build. When running `storybook build`, this feature is enabled by setting the `--test` [flag](https://storybook.js.org/docs/api/cli-options.md#build).

The options documented on this page are automatically enabled when the `--test` flag is provided to the [`storybook build`](https://storybook.js.org/docs/api/cli-options.md#build) command. We encourage you to override these options only if you need to disable a specific feature for your project or if you are debugging a build issue.

### `test.disableBlocks`

Type: `boolean`

Excludes the `@storybook/addon-docs/blocks` module from the build, which generates automatic documentation with [Docs Blocks](https://storybook.js.org/docs/writing-docs/doc-blocks.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableBlocks: false,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableBlocks: false,
    },
  },
});
```

### `test.disabledAddons`

Type: `string[]`

Sets the list of addons that will be disabled in the build output.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-a11y', '@storybook/addon-vitest'],
  build: {
    test: {
      disabledAddons: ['@storybook/addon-a11y'],
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-a11y', '@storybook/addon-vitest'],
  build: {
    test: {
      disabledAddons: ['@storybook/addon-a11y'],
    },
  },
});
```

### `test.disableMDXEntries`

Type: `boolean`

Enabling this option removes user-written documentation entries in MDX format from the build.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableMDXEntries: false,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableMDXEntries: false,
    },
  },
});
```

### `test.disableAutoDocs`

Type: `boolean`

Prevents automatic documentation generated with the [autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md) feature from being included in the build.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableAutoDocs: false,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableAutoDocs: false,
    },
  },
});
```

### `test.disableDocgen`

Type: `boolean`

Disables [automatic argType](https://storybook.js.org/docs/api/arg-types.md#automatic-argtype-inference) and component property inference with any of the supported static analysis tools based on the framework you are using.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableDocgen: false,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableDocgen: false,
    },
  },
});
```

### `test.disableSourcemaps`

Type: `boolean`

Overrides the default behavior of generating source maps for the build.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableSourcemaps: false,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableSourcemaps: false,
    },
  },
});
```

### `test.disableTreeShaking`

Type: `boolean`

Disables [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) in the build.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableTreeShaking: false,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableTreeShaking: false,
    },
  },
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-build
---

# core

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type:

```ts
{
  allowedHosts?: string[] | true;
  builder?: string | { name: string; options?: BuilderOptions };
  channelOptions?: ChannelOptions;
  crossOriginIsolated?: boolean;
  disableProjectJson?: boolean;
  disableTelemetry?: boolean;
  disableWebpackDefaults?: boolean;
  disableWhatsNewNotifications?: boolean;
  enableCrashReports?: boolean;
  renderer?: RendererName;
}
```

Configures Storybook's internal features.

## `allowedHosts`

Type: `string[] | true`

Default: `[]`

Configures the allowed hosts for the Storybook dev server, used for Origin and Host header validation. Storybook's localhost and local network (or [`--host`](https://storybook.js.org/docs/api/cli-options.md#dev)) addresses are always allowed. Use this when accessing your local Storybook instance through a reverse proxy (e.g. your webapp dev server). Set to `true` to disable hostname validation (insecure).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    allowedHosts: ['storybook.example.local'],
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  framework: '@storybook/your-framework',
  core: {
    allowedHosts: ['storybook.example.local'],
  },
});
```

## `builder`

Type:

```ts
| '@storybook/builder-vite' | '@storybook/builder-webpack5'
| {
    name: '@storybook/builder-vite' | '@storybook/builder-webpack5';
    options?: BuilderOptions;
  }
```

Configures Storybook's builder, [Vite](https://storybook.js.org/docs/builders/vite.md) or [Webpack](https://storybook.js.org/docs/builders/webpack.md).

With the new [Framework API](https://storybook.js.org/docs/api/new-frameworks.md), [`framework.options.builder`](https://storybook.js.org/docs/api/main-config/main-config-framework.md#optionsbuilder) is now the preferred way to configure the builder.

You should only use `core.builder.options` if you need to configure a builder that is not part of a framework.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  framework: '@storybook/your-framework',
  core: {
    builder: {
      name: '@storybook/builder-vite',
      options: {
        viteConfigPath: '../../../vite.config.js',
      },
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  framework: '@storybook/your-framework',
  core: {
    builder: {
      name: '@storybook/builder-vite',
      options: {
        viteConfigPath: '../../../vite.config.js',
      },
    },
  },
});
```

## `channelOptions`

Type: `ChannelOptions`

```ts
{
  allowDate: boolean;
  allowRegExp: boolean;
  allowSymbol: boolean;
  allowUndefined: boolean;
  maxDepth: number;
  space: number | undefined;
}
```

Configures the channel used by Storybook to communicate between the manager and preview.

Only two properties are likely to be used:

### `channelOptions.maxDepth`

Type: `number`

Default: `3`

The maximum depth of nested objects to serialize across the channel. Larger values will be slower.

## `crossOriginIsolated`

Type: `boolean`

Enable CORS headings to run document in a "secure context". See [SharedArrayBuffer security requirements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements)

This enables these headers in development-mode:

- `Cross-Origin-Opener-Policy: same-origin`
- `Cross-Origin-Embedder-Policy: require-corp`

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    crossOriginIsolated: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    crossOriginIsolated: true,
  },
});
```

## `disableProjectJson`

Type: `boolean`

Disables the generation of `project.json`, a file containing Storybook metadata

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableProjectJson: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableProjectJson: true,
  },
});
```

## `disableTelemetry`

Type: `boolean`

Disables Storybook's [telemetry collection](https://storybook.js.org/docs/configure/telemetry.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableTelemetry: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableTelemetry: true,
  },
});
```

## `disableWebpackDefaults`

Type: `boolean`

Disables Storybook's default Webpack configuration.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableWebpackDefaults: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableWebpackDefaults: true,
  },
});
```

## `disableWhatsNewNotifications`

Type: `boolean`

Disables the "What's New" notifications in the UI for new Storybook versions and ecosystem updates (e.g., [addons](https://storybook.js.org/integrations/), [content](https://storybook.js.org/blog/), etc.).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableWhatsNewNotifications: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    disableWhatsNewNotifications: true,
  },
});
```

## `enableCrashReports`

Type: `boolean`

Enable crash reports to be sent to Storybook [telemetry](https://storybook.js.org/docs/configure/telemetry.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    enableCrashReports: true, // 👈 Appends the crash reports to the telemetry events
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    enableCrashReports: true, // 👈 Appends the crash reports to the telemetry events
  },
});
```

## `renderer`

Type: `RendererName`
> Source: https://storybook.js.org/docs/api/main-config/main-config-core
---

# docs

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type:

```ts
{
  defaultName?: string;
  docsMode?: boolean;
}
```

Configures Storybook's [auto-generated documentation](https://storybook.js.org/docs/writing-docs/autodocs.md).

## `defaultName`

Type: `string`

Default: `'Docs'`

Name used for generated documentation pages.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  docs: {
    defaultName: 'Documentation',
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  docs: {
    defaultName: 'Documentation',
  },
});
```

## `docsMode`

Type: `boolean`

Only show documentation pages in the sidebar (usually set with the `--docs` CLI flag).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  docs: {
    docsMode: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  docs: {
    docsMode: true,
  },
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-docs
---

# env

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(config: { [key: string]: string }) => { [key: string]: string }`

Defines custom Storybook [environment variables](https://storybook.js.org/docs/configure/environment-variables.md#using-storybook-configuration).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  /*
   * 👇 The `config` argument contains all the other existing environment variables.
   * Either configured in an `.env` file or configured on the command line.
   */
  env: (config) => ({
    ...config,
    EXAMPLE_VAR: 'An environment variable configured in Storybook',
  }),
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  /*
   * 👇 The `config` argument contains all the other existing environment variables.
   * Either configured in an `.env` file or configured on the command line.
   */
  env: (config) => ({
    ...config,
    EXAMPLE_VAR: 'An environment variable configured in Storybook',
  }),
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-env
---

# features

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type:

```ts
{
  actions?: boolean;
  argTypeTargetsV7?: boolean;
  backgrounds?: boolean;
  changeDetection?: boolean;
  componentsManifest?: boolean;
  controls?: boolean;
  developmentModeForBuild?: boolean;
  experimentalCodeExamples?: boolean;
  experimentalTestSyntax?: boolean;
  highlight?: boolean;
  interactions?: boolean;
  legacyDecoratorFileOrder?: boolean;
  measure?: boolean;
  outline?: boolean;
  sidebarOnboardingChecklist?: boolean;
  toolbars?: boolean;
  viewport?: boolean;
}
```

```ts
{
  actions?: boolean;
  argTypeTargetsV7?: boolean;
  backgrounds?: boolean;
  changeDetection?: boolean;
  controls?: boolean;
  developmentModeForBuild?: boolean;
  highlight?: boolean;
  interactions?: boolean;
  legacyDecoratorFileOrder?: boolean;
  measure?: boolean;
  outline?: boolean;
  sidebarOnboardingChecklist?: boolean;
  toolbars?: boolean;
  viewport?: boolean;
}
```

Enables Storybook's additional features.

## `actions`

Type: `boolean`

Default: `true`

Enable the [Actions](https://storybook.js.org/docs/essentials/actions.md) feature.

## `argTypeTargetsV7`

(⚠️ **Experimental**)

Type: `boolean`

Default: `true`

Filter args with a "target" on the type from the render function.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    argTypeTargetsV7: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    argTypeTargetsV7: true,
  },
});
```

## `backgrounds`

Type: `boolean`

Default: `true`

Enable the [Backgrounds](https://storybook.js.org/docs/essentials/backgrounds.md) feature.

## `componentsManifest`

Type: `boolean`

Default: `false`

Generate [manifests](https://storybook.js.org/docs/ai/manifests.md), used by the [MCP server](https://storybook.js.org/docs/ai/mcp/overview.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    componentsManifest: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    componentsManifest: true,
  },
});
```

## `changeDetection`

Type: `boolean`

Default: `true`

Enable [change detection](https://storybook.js.org/docs/configure/user-interface/change-detection.md). When enabled, Storybook monitors your git working tree and the builder's module graph to show which stories are new, modified, or related to code changes. Changed stories are displayed with status icons in the sidebar.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    changeDetection: false,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    changeDetection: false,
  },
});
```

## `controls`

Type: `boolean`

Default: `true`

Enable the [Controls](https://storybook.js.org/docs/essentials/controls.md) feature.

## `developmentModeForBuild`

Type: `boolean`

Set `NODE_ENV` to `'development'` in built Storybooks for better testing and debugging capabilities.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    developmentModeForBuild: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    developmentModeForBuild: true,
  },
});
```

## `experimentalCodeExamples`

(⚠️ **Experimental**)

Type: `boolean`

Enable the new code example generation method for React components (as seen in the story previews in an [autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md) page).

Unlike the current implementation, this method reads the actual stories source file, which is faster to generate, more readable, and more accurate. However, they are not dynamic: they won't update if you change values in the Controls table.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    experimentalCodeExamples: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    experimentalCodeExamples: true,
  },
});
```

## `experimentalTestSyntax`

(⚠️ **Experimental**)

Type: `boolean`

Enable the [experimental `.test` method with the CSF Next format](https://storybook.js.org/docs/api/csf/csf-next.md#storytest).

```ts
// .storybook/main.js|ts (CSF Next 🧪)
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    experimentalTestSyntax: true,
  },
});
```

## `highlight`

Type: `boolean`

Default: `true`

Enable the [Highlight](https://storybook.js.org/docs/essentials/highlight.md) feature.

## `interactions`

Type: `boolean`

Default: `true`

Enable the [Interactions](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests) feature.

## `legacyDecoratorFileOrder`

Type: `boolean`

Apply decorators from preview.js before decorators from addons or frameworks. [More information](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#changed-decorator-order-between-previewjs-and-addonsframeworks).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    legacyDecoratorFileOrder: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    legacyDecoratorFileOrder: true,
  },
});
```

## `measure`

Type: `boolean`

Default: `true`

Enable the [Measure](https://storybook.js.org/docs/essentials/measure-and-outline.md#measure) feature.

## `outline`

Type: `boolean`

Default: `true`

Enable the [Outline](https://storybook.js.org/docs/essentials/measure-and-outline.md#outline) feature.

## `sidebarOnboardingChecklist`

Type: `boolean`

Default: `true`

Enable the onboarding checklist sidebar widget.

## `viewport`

Type: `boolean`

Default: `true`

Enable the [Viewport](https://storybook.js.org/docs/essentials/viewport.md) feature.
> Source: https://storybook.js.org/docs/api/main-config/main-config-features
---

# indexers

(⚠️ **Experimental**)

While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](https://storybook.js.org/docs/api/main-config/main-config.md).

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(existingIndexers: Indexer[]) => Promise<Indexer[]>`

Indexers are responsible for building Storybook's index of stories—the list of all stories and a subset of their metadata like `id`, `title`, `tags`, and more. The index can be read at the `/index.json` route of your Storybook.

The indexers API is an advanced feature that allows you to customize Storybook's indexers, which dictate how Storybook indexes and parses files into story entries. This adds more flexibility to how you can write stories, including which language stories are defined in or where to get stories from.

They are defined as a function that returns the full list of indexers, including the existing ones. This allows you to add your own indexer to the list, or to replace an existing one:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    // 👇 Make sure files to index are included in `stories`
    '../src/**/*.custom-stories.@(js|jsx|ts|tsx)',
  ],
  experimental_indexers: async (existingIndexers) => {
    const customIndexer = {
      test: /\.custom-stories\.[tj]sx?$/,
      createIndex: async (fileName) => {
        // See API and examples below...
      },
    };
    return [...existingIndexers, customIndexer];
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    // 👇 Make sure files to index are included in `stories`
    '../src/**/*.custom-stories.@(js|jsx|ts|tsx)',
  ],
  experimental_indexers: async (existingIndexers) => {
    const customIndexer = {
      test: /\.custom-stories\.[tj]sx?$/,
      createIndex: async (fileName) => {
        // See API and examples below...
      },
    };
    return [...existingIndexers, customIndexer];
  },
});
```

Unless your indexer is doing something relatively trivial (e.g. [indexing stories with a different naming convention](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#story-indexers)), in addition to indexing the file, you will likely need to [transpile it to CSF](#transpiling-to-csf) so that Storybook can read them in the browser.

## `Indexer`

Type:

```ts
{
  test: RegExp;
  createIndex: (fileName: string, options: IndexerOptions) => Promise<IndexInput[]>;
}
```

Specifies which files to index and how to index them as stories.

### `test`

(Required)

Type: `RegExp`

A regular expression run against file names included in the [`stories`](https://storybook.js.org/docs/api/main-config/main-config-stories.md) configuration that should match all files to be handled by this indexer.

### `createIndex`

(Required)

Type: `(fileName: string, options: IndexerOptions) => Promise<IndexInput[]>`

Function that accepts a single CSF file and returns a list of entries to index.

#### `fileName`

Type: `string`

The name of the CSF file used to create entries to index.

#### `IndexerOptions`

Type:

```ts
{
  makeTitle: (userTitle?: string) => string;
}
```

Options for indexing the file.

##### `makeTitle`

Type: `(userTitle?: string) => string`

A function that takes a user-provided title and returns a formatted title for the index entry, which is used in the sidebar. If no user title is provided, one is automatically generated based on the file name and path.

See [`IndexInput.title`](#title) for example usage.

#### `IndexInput`

Type:

```ts
{
  exportName: string;
  importPath: string;
  type: 'story';
  subtype?: 'story' | 'test';
  rawComponentPath?: string;
  metaId?: string;
  name?: string;
  tags?: string[];
  title?: string;
  __id?: string;
}
```

An object representing a story to be added to the stories index.

##### `exportName`

(Required)

Type: `string`

For each `IndexInput`, the indexer will add this export (from the file found at `importPath`) as an entry in the index.

##### `importPath`

Type: `string`

Default: The original [`fileName`](#filename) passed to the `createIndex` function

The file to import from, e.g. the [CSF](https://storybook.js.org/docs/api/csf.md) file.

It is likely that the [`fileName`](#filename) being indexed is not CSF, in which you will need to [transpile it to CSF](#transpiling-to-csf) so that Storybook can read it in the browser.

⚠️ Custom `importPath`s are only supported in Vite-based projects. To use them in Webpack-based projects, you will need to [transpile the source file to CSF](#transpiling-to-csf) and leave `importPath` empty to use the original `fileName`.

##### `type`

(Required)

Type: `'story'`

The type of entry.

##### `subtype`

(⚠️ **Experimental**)

Type: `'story' | 'test'`

Default: `'story'`

The subtype of the story entry when [`type`](#type) is `'story'`. Use this to mark an entry as a [_test_ (experimental)](https://github.com/storybookjs/storybook/discussions/30119). If not specified, defaults to `'story'`.

##### `rawComponentPath`

Type: `string`

The raw path/package of the file that provides `meta.component`, if one exists.

##### `metaId`

Type: `string`

Default: Auto-generated from [`title`](#title)

Define the custom id for meta of the entry.

If specified, the export default (meta) in the CSF file _must_ have a corresponding `id` property, to be correctly matched.

##### `name`

Type: `string`

Default: Auto-generated from [`exportName`](#exportname)

The name of the entry.

##### `tags`

Type: `string[]`

Tags for filtering entries in Storybook and its tools.

##### `title`

Type: `string`

Default: Auto-generated from the meta (or default export) of [`importPath`](#importpath)

Determines the location of the entry in the sidebar.

Most of the time, you should **not** specify a title, so that your indexer will use the default naming behavior. When specifying a title, you **must** use the [`makeTitle`](#maketitle) function provided in [`IndexerOptions`](#indexeroptions) to also use this behavior. For example, here's an indexer that merely appends a "Custom" prefix to the title derived from the file name:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const combosIndexer: Indexer = {
  test: /\.stories\.[tj]sx?$/,
  createIndex: async (fileName, { makeTitle }) => {
    // 👇 Grab title from fileName
    const title = fileName.match(/\/(.*)\.stories/)[1];

    // Read file and generate entries ...
    const entries = [];

    return entries.map((entry) => ({
      type: 'story',
      // 👇 Use makeTitle to format the title
      title: `${makeTitle(title)} Custom`,
      importPath: fileName,
      exportName: entry.name,
    }));
  },
};

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  experimental_indexers: async (existingIndexers) => [...existingIndexers, combosIndexer],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const combosIndexer: Indexer = {
  test: /\.stories\.[tj]sx?$/,
  createIndex: async (fileName, { makeTitle }) => {
    // 👇 Grab title from fileName
    const title = fileName.match(/\/(.*)\.stories/)[1];

    // Read file and generate entries ...
    const entries = [];

    return entries.map((entry) => ({
      type: 'story',
      // 👇 Use makeTitle to format the title
      title: `${makeTitle(title)} Custom`,
      importPath: fileName,
      exportName: entry.name,
    }));
  },
};

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  experimental_indexers: async (existingIndexers) => [...existingIndexers, combosIndexer],
});
```

##### `__id`

Type: `string`

Default: Auto-generated from [`title`](#title)/[`metaId`](#metaid) and [`exportName`](#exportname)

Define the custom id for the story of the entry.

If specified, the story in the CSF file **must** have a corresponding `__id` property, to be correctly matched.

Only use this if you need to override the auto-generated id.

## Transpiling to CSF

The value of [`importPath`](#importpath) in an [`IndexInput`](#indexinput) must resolve to a [CSF](https://storybook.js.org/docs/api/csf.md) file. Most custom indexers, however, are only necessary because the input is _not_ CSF. Therefore, you will likely need to transpile the input to CSF, so that Storybook can read it in the browser and render your stories.

Transpiling the custom source format to CSF is beyond the scope of this documentation. This transpilation is often done at the builder level ([Vite](https://storybook.js.org/docs/builders/vite.md) and/or [Webpack](https://storybook.js.org/docs/builders/webpack.md)), and we recommend using [unplugin](https://github.com/unjs/unplugin) to create plugins for multiple builders.

The general architecture looks something like this:

![Architecture diagram showing how a custom indexer indexes stories from a source file](../../_assets/api/main-config-indexers-arch-indexer.jpg)

1. Using the [`stories`](https://storybook.js.org/docs/api/main-config/main-config-stories.md) configuration, Storybook finds all files that match the [`test`](#test) property of your indexer
2. Storybook passes each matching file to your indexer's [`createIndex` function](#createindex), which uses the file contents to generate and return a list of index entries (stories) to add to the index
3. The index populates the sidebar in the Storybook UI

![Architecture diagram showing how a build plugin transforms a source file into CSF](../../_assets/api/main-config-indexers-arch-build-plugin.jpg)

4. In the Storybook UI, the user navigates to a URL matching the story id and the browser requests the CSF file specified by the [`importPath`](#importpath) property of the index entry
5. Back on the server, your builder plugin transpiles the source file to CSF, and serves it to the client
6. The Storybook UI reads the CSF file, imports the story specified by [`exportName`](#exportname), and renders it

Let's look at an example of how this might work.

First, here's an example of a non-CSF source file:

```ts
// Button.variants.js|ts

/**
 * Returns raw strings representing stories via component props, eg.
 * 'export const PrimaryVariant = {
 *    args: {
 *      primary: true
 *    },
 *  };'
 */
export const generateStories = () => {
  const variants = variantsFromComponent(Button);
  return variants.map((variant) => createStoryFromVariant(variant));
};
```

The builder plugin would then:

1. Receive and read the source file
2. Import the exported `generateStories` function
3. Run the function to generate the stories
4. Write the stories to a CSF file

That resulting CSF file would then be indexed by Storybook. It would look something like this:

```js
// virtual:Button.variants.js|ts

export default {
  component: Button,
};

export const Primary = {
  args: {
    primary: true,
  },
};
```

## Examples

Some example usages of custom indexers include:

<details open>
<summary>Generating stories dynamically from fixture data or API endpoints</summary>

This indexer generates stories for components based on JSON fixture data. It looks for `*.stories.json` files in the project, adds them to the index and separately converts their content to CSF.

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const jsonStoriesIndexer: Indexer = {
  test: /stories\.json$/,
  createIndex: async (fileName) => {
    const content = JSON.parse(fs.readFileSync(fileName));

    const stories = generateStoryIndexesFromJson(content);

    return stories.map((story) => ({
      type: 'story',
      importPath: `virtual:jsonstories--${fileName}--${story.componentName}`,
      exportName: story.name,
    }));
  },
};

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    // 👇 Make sure files to index are included in `stories`
    '../src/**/*.stories.json',
  ],
  experimental_indexers: async (existingIndexers) => [...existingIndexers, jsonStoriesIndexer],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const jsonStoriesIndexer: Indexer = {
  test: /stories\.json$/,
  createIndex: async (fileName) => {
    const content = JSON.parse(fs.readFileSync(fileName));

    const stories = generateStoryIndexesFromJson(content);

    return stories.map((story) => ({
      type: 'story',
      importPath: `virtual:jsonstories--${fileName}--${story.componentName}`,
      exportName: story.name,
    }));
  },
};

export default defineMain({
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    // 👇 Make sure files to index are included in `stories`
    '../src/**/*.stories.json',
  ],
  experimental_indexers: async (existingIndexers) => [...existingIndexers, jsonStoriesIndexer],
});
```

An example input JSON file could look like this:

```json
{
  "Button": {
    "componentPath": "./button/Button.jsx",
    "stories": {
      "Primary": {
        "args": {
          "primary": true
        }
      },
      "Secondary": {
        "args": {
          "primary": false
        }
      }
    }
  },
  "Dialog": {
    "componentPath": "./dialog/Dialog.jsx",
    "stories": {
      "Closed": {},
      "Open": {
        "args": {
          "isOpen": true
        }
      }
    }
  }
}
```

A builder plugin will then need to transform the JSON file into a regular CSF file. This transformation could be done with a Vite plugin similar to this:

```ts
// vite-plugin-storybook-json-stories.ts

function JsonStoriesPlugin(): PluginOption {
  return {
    name: 'vite-plugin-storybook-json-stories',
    load(id) {
      if (!id.startsWith('virtual:jsonstories')) {
        return;
      }

      const [, fileName, componentName] = id.split('--');
      const content = JSON.parse(fs.readFileSync(fileName));

      const { componentPath, stories } = getComponentStoriesFromJson(content, componentName);

      return `
        import ${componentName} from '${componentPath}';

        export default { component: ${componentName} };

        ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)}
      `;
    },
  };
}
```

</details>

<details>
<summary>Generating stories with an alternative API</summary>

You can use a custom indexer and builder plugin to create your API to define stories extending the CSF format. To learn more, see the following [proof of concept](https://stackblitz.com/edit/github-h2rgfk?file=README.md) to set up a custom indexer to generate stories dynamically. It contains everything needed to support such a feature, including the indexer, a Vite plugin, and a Webpack loader.

</details>

<details>
<summary>Defining stories in non-JavaScript language</summary>

Custom indexers can be used for an advanced purpose: defining stories in any language, including template languages, and converting the files to CSF. To see examples of this in action, you can refer to [`@storybook/addon-svelte-csf`](https://github.com/storybookjs/addon-svelte-csf) for Svelte template syntax and [`storybook-vue-addon`](https://github.com/tobiasdiez/storybook-vue-addon) for Vue template syntax.

</details>

<details>
<summary>Adding sidebar links from a URL collection</summary>

The indexer API is flexible enough to let you process arbitrary content, so long as your framework tooling can transform the exports in that content into actual stories it can run. This advanced example demonstrates how you can create a custom indexer to process a collection of URLs, extract the title and URL from each page, and render them as sidebar links in the UI. Implemented with Svelte, it can be adapted to any framework.

Start by creating the URL collection file (i.e., `src/MyLinks.url.js`) with a list of URLs listed as named exports. The indexer will use the export name as the story title and the value as the unique identifier.

```js title="MyLinks.url.js"
export default {};

export const DesignTokens = 'https://www.designtokens.org/';
export const CobaltUI = 'https://cobalt-ui.pages.dev/';
export const MiseEnMode = 'https://mode.place/';
export const IndexerAPI = 'https://github.com/storybookjs/storybook/discussions/23176';
```

Adjust your Vite configuration file to include a custom plugin complementing the indexer. This will allow Storybook to process and import the URL collection file as stories.

```ts title="vite.config.ts"

function StorybookUrlLinksPlugin(): Plugin {
  return {
    name: 'storybook-url-links',
    async transform(code: string, id: string) {
      if (id.endsWith('.url.js')) {
        const ast = acorn.parse(code, {
          ecmaVersion: 2020,
          sourceType: 'module',
        });

        const namedExports: string[] = [];
        let defaultExport = 'export default {};';

        walk.simple(ast, {
          // Extracts the named exports, those represent our stories, and for each of them, we'll return a valid Svelte component.
          ExportNamedDeclaration(node: acorn.ExportNamedDeclaration) {
            if (node.declaration && node.declaration.type === 'VariableDeclaration') {
              node.declaration.declarations.forEach((declaration) => {
                if ('name' in declaration.id) {
                  namedExports.push(declaration.id.name);
                }
              });
            }
          },
          // Preserve our default export.
          ExportDefaultDeclaration(node: acorn.ExportDefaultDeclaration) {
            defaultExport = code.slice(node.start, node.end);
          },
        });

        return {
          code: `
            import RedirectBack from '../../.storybook/components/RedirectBack.svelte';
            ${namedExports
              .map((name) => `export const ${name} = () => new RedirectBack();`)
              .join('\n')}
            ${defaultExport}
          `,
          map: null,
        };
      }
    },
  };
}

export default defineConfig({
  plugins: [StorybookUrlLinksPlugin(), svelte()],
});
```

Update your Storybook configuration (i.e., `.storybook/main.js|ts`) to include the custom indexer.

```ts title=".storybook/main.js|ts"
// Replace your-framework with the framework you are using, e.g. sveltekit or svelte-vite

const urlIndexer: Indexer = {
  test: /\.url\.js$/,
  createIndex: async (fileName, { makeTitle }) => {
    const fileData = await import(fileName);

    return Object.entries(fileData)
      .filter(([key]) => key != 'default')
      .map(([name, url]) => {
        return {
          type: 'docs',
          importPath: fileName,
          exportName: name,
          title: makeTitle(name)
            .replace(/([a-z])([A-Z])/g, '$1 $2')
            .trim(),
          __id: `url--${name}--${encodeURIComponent(url as string)}`,
          tags: ['!autodocs', 'url'],
        };
      });
  },
};

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|ts|svelte)', '../src/**/*.url.js'],
  framework: {
    name: '@storybook/svelte-vite',
    options: {},
  },
  experimental_indexers: async (existingIndexers) => [urlIndexer, ...existingIndexers],
};
export default config;
```

Add a Storybook UI configuration file (i.e., `.storybook/manager.js|ts`) to render the indexed URLs as sidebar links in the UI:

```ts title=".storybook/manager.ts"

addons.setConfig({
  sidebar: {
    renderLabel: (item) => SidebarLabelWrapper({ item }),
  },
});
```

This example's code and live demo are available on [StackBlitz](https://stackblitz.com/~/github.com/Sidnioulz/storybook-sidebar-urls).

</details>
> Source: https://storybook.js.org/docs/api/main-config/main-config-indexers
---

# logLevel

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `'debug' | 'error' | 'info' | 'trace' | 'warn'`

Default: `'info'`

Configures Storybook's logs in the browser terminal. Useful for debugging.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  logLevel: 'debug',
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  logLevel: 'debug',
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-log-level
---

# managerHead

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(head: string) => string`

Programmatically adjust the manager's `<head>` of your Storybook. For example, load a custom font or add a script. Most often used by [addon authors](https://storybook.js.org/docs/addons/writing-presets.md#ui-configuration).

If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead.

For example, you can conditionally add scripts or styles, depending on the environment:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  managerHead: (head) => `
    ${head}
    <link rel="preload" href="/fonts/my-custom-manager-font.woff2" />
  `,
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  managerHead: (head) => `
    ${head}
    <link rel="preload" href="/fonts/my-custom-manager-font.woff2" />
  `,
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-manager-head
---

# previewAnnotations

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `string[] | ((config: string[], options: Options) => string[] | Promise<string[]>)`

Add additional scripts to run in the story preview.

Mostly used by [frameworks](https://storybook.js.org/docs/contribute/framework.md#previewjs-example). Storybook users and [addon authors](https://storybook.js.org/docs/addons/writing-presets.md) should add scripts to [`preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) instead.

```ts
// @storybook/nextjs framework's src/preset.ts

export const previewAnnotations: StorybookConfig['previewAnnotations'] = (entry = []) => [
  ...entry,
  import.meta.resolve('@storybook/nextjs/preview'),
];
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-preview-annotations
---

# previewBody

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(body: string) => string`

Programmatically adjust the [preview `<body>`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-body) of your Storybook. Most often used by [addon authors](https://storybook.js.org/docs/addons/writing-presets.md#ui-configuration).

If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-body) instead.

For example, you can conditionally add scripts or styles, depending on the environment:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  previewBody: (body) => `
    ${body}
    ${
      process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
    }
  `,
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  previewBody: (body) => `
    ${body}
    ${
      process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
    }
  `,
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-preview-body
---

# previewHead

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(head: string) => string`

Programmatically adjust the [preview `<head>`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-head) of your Storybook. Most often used by [addon authors](https://storybook.js.org/docs/addons/writing-presets.md#ui-configuration).

If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](https://storybook.js.org/docs/configure/story-rendering.md#adding-to-head) instead.

For example, you can conditionally add scripts or styles, depending on the environment:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  previewHead: (head) => `
    ${head}
    ${
      process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
    }
  `,
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  previewHead: (head) => `
    ${head}
    ${
      process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
    }
  `,
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-preview-head
---

# refs

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type:

```ts
{ [key: string]:
  | { title: string; url: string; expanded?: boolean, sourceUrl?: string }
  | (config: { title: string; url: string; expanded?: boolean, sourceUrl: string }) => { title: string; url: string; expanded?: boolean, sourceUrl?: string }
  | { disable: boolean }
}
```

Configures [Storybook composition](https://storybook.js.org/docs/sharing/storybook-composition.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'design-system': {
      title: 'Storybook Design System',
      url: 'https://master--5ccbc373887ca40020446347.chromatic.com/',
      expanded: false, // Optional, true by default,
      sourceUrl: 'https://github.com/storybookjs/storybook', // Optional
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'design-system': {
      title: 'Storybook Design System',
      url: 'https://master--5ccbc373887ca40020446347.chromatic.com/',
      expanded: false, // Optional, true by default,
      sourceUrl: 'https://github.com/storybookjs/storybook', // Optional
    },
  },
});
```

## Using a function

You can use a function to dynamically configure refs:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // 👇 Retrieve the current environment from the configType argument
  refs: (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      return {
        react: {
          title: 'Composed React Storybook running in development mode',
          url: 'http://localhost:7007',
        },
        angular: {
          title: 'Composed Angular Storybook running in development mode',
          url: 'http://localhost:7008',
        },
      };
    }
    return {
      react: {
        title: 'Composed React Storybook running in production',
        url: 'https://your-production-react-storybook-url',
      },
      angular: {
        title: 'Composed Angular Storybook running in production',
        url: 'https://your-production-angular-storybook-url',
      },
    };
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // 👇 Retrieve the current environment from the configType argument
  refs: (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      return {
        react: {
          title: 'Composed React Storybook running in development mode',
          url: 'http://localhost:7007',
        },
        angular: {
          title: 'Composed Angular Storybook running in development mode',
          url: 'http://localhost:7008',
        },
      };
    }
    return {
      react: {
        title: 'Composed React Storybook running in production',
        url: 'https://your-production-react-storybook-url',
      },
      angular: {
        title: 'Composed Angular Storybook running in production',
        url: 'https://your-production-angular-storybook-url',
      },
    };
  },
});
```

## Disable a ref

Some package dependencies automatically [compose their Storybook in yours](https://storybook.js.org/docs/sharing/package-composition.md). You can disable this behavior by setting `disable` to `true` for the package name:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'package-name': { disable: true },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  refs: {
    'package-name': { disable: true },
  },
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-refs
---

# staticDirs

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(string | { from: string; to: string })[]`

Sets a list of directories of [static files](https://storybook.js.org/docs/configure/integration/images-and-assets.md#serving-static-files-via-storybook-configuration) to be loaded by Storybook.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
});
```

When using Vite-based frameworks, additional directories may be copied to your build directory because of Vite's own [static asset handling](https://vite.dev/guide/assets#the-public-directory). You can set Vite's `publicDir` option to `false` to disable this behavior.

## With configuration objects

You can also use a configuration object to define the directories:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: [{ from: '../my-custom-assets/images', to: '/assets' }],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: [{ from: '../my-custom-assets/images', to: '/assets' }],
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-static-dirs
---

# swc

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(config: swc.Options, options: Options) => swc.Options | Promise<swc.Options>`

Customize Storybook's [SWC](https://swc.rs/) setup for Webpack-based projects enabled via the [`@storybook/addon-webpack5-compiler-swc`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-swc) addon based on the supported [frameworks](https://storybook.js.org/docs/configure/integration/frameworks.md), except Angular, Create React App, Ember.js and Next.js.

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with the webpack-based framework you are using (e.g., react-webpack5)

const config: StorybookConfig = {
  framework: {
    name: '@storybook/your-framework',
    options: {},
  },
  swc: (config: Options, options): Options => {
    return {
      ...config,
      // Apply your custom SWC configuration
    };
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: {
    name: '@storybook/your-framework',
    options: {},
  },
  swc: (config: Options, options): Options => {
    return {
      ...config,
      // Apply your custom SWC configuration
    };
  },
});
```

## `SWC.Options`

The options provided by [SWC](https://swc.rs/) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-swc`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-swc) addon.

## Options

Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }`

There are other options that are difficult to document here. Please introspect the type definition for more information.
> Source: https://storybook.js.org/docs/api/main-config/main-config-swc
---

# tags

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `{ [tagName: string]: { defaultFilterSelection?: 'include' | 'exclude' } }`

Define custom [tags](https://storybook.js.org/docs/writing-stories/tags.md) for your stories, or alter the default configuration of built-in tags.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Define a custom tag named "experimental"
    experimental: {
      defaultFilterSelection: 'exclude', // Or 'include'
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Define a custom tag named "experimental"
    experimental: {
      defaultFilterSelection: 'exclude', // Or 'include'
    },
  },
});
```

## `[tagName]`

Type: `string`

The name of the tag. This can be any static (i.e. not created dynamically) string, either a built-in tag or a custom tag of your own design.

### `[tagName].defaultFilterSelection`

Type: `'include' | 'exclude'`

Set the default filter selection state for a tag in the Storybook sidebar. If set to `include`, stories with this tag are selected as included. If set to `exclude`, stories with this tag are selected as excluded, and must be explicitly included by selecting the tag in the sidebar filter menu. If not set, the tag has no default selection.

![Filtering by tags](../../_assets/writing-stories/tag-filter.png)
> Source: https://storybook.js.org/docs/api/main-config/main-config-tags
---

# typescript

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type:

```ts
{
  check?: boolean;
  checkOptions?: CheckOptions;
  reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false;
  reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions;
  skipCompiler?: boolean;
}
```

```ts
{
  check?: boolean;
  checkOptions?: CheckOptions;
  skipCompiler?: boolean;
}
```

Configures how Storybook handles [TypeScript files](https://storybook.js.org/docs/configure/integration/typescript.md).

## `check`

Type: `boolean`

Optionally run [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin). Note that because this uses a Webpack plugin, it is only available when using the [Webpack builder](https://storybook.js.org/docs/builders/webpack.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: true,
  },
});
```

## `checkOptions`

Type: `CheckOptions`

Options to pass to `fork-ts-checker-webpack-plugin`, if [enabled](#check). See [docs for available options](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/blob/v4.1.6/README.md#options).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: true,
    checkOptions: {
      eslint: true,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-webpack5, nextjs, nextjs-webpack5)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: true,
    checkOptions: {
      eslint: true,
    },
  },
});
```

## `reactDocgen`

Type: `'react-docgen' | 'react-docgen-typescript' | false`

Default:

- `false`: if `@storybook/react` is not installed
- `'react-docgen'`: if `@storybook/react` is installed

Configures which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen',
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen',
  },
});
```

## `reactDocgenTypescriptOptions`

Type: `ReactDocgenTypescriptOptions`

Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See docs for available options [for Webpack projects](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) or [for Vite projects](https://github.com/joshwooding/vite-plugin-react-docgen-typescript).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      // 👇 Default prop filter, which excludes props from node_modules
      propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      // 👇 Default prop filter, which excludes props from node_modules
      propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
    },
  },
});
```

## `skipCompiler`

Type: `boolean`

Disable parsing of TypeScript files through the compiler, which is used for Webpack5.

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    skipCompiler: true,
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    skipCompiler: true,
  },
});
```
> Source: https://storybook.js.org/docs/api/main-config/main-config-typescript
---

# viteFinal

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `(config: Vite.InlineConfig, options: Options) => Vite.InlineConfig | Promise<Vite.InlineConfig>`

Customize Storybook's Vite setup when using the [Vite builder](https://storybook.js.org/docs/builders/vite.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs-vite, vue3-vite, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config, { configType }) {
    const { mergeConfig } = await import('vite');

    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return mergeConfig(config, {
      // Your environment configuration here
    });
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async viteFinal(config, { configType }) {
    const { mergeConfig } = await import('vite');

    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return mergeConfig(config, {
      // Your environment configuration here
    });
  },
});
```

## `Options`

Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }`

There are other options that are difficult to document here. Please introspect the type definition for more information.
> Source: https://storybook.js.org/docs/api/main-config/main-config-vite-final
---

# webpackFinal

Parent: [main.js|ts configuration](https://storybook.js.org/docs/api/main-config/main-config.md)

Type: `async (config: Config, options: WebpackOptions) => Config`

Customize Storybook's Webpack setup when using the [webpack builder](https://storybook.js.org/docs/builders/webpack.md).

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
});
```

## `Options`

Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }`

There are other options that are difficult to document here. Please introspect the type definition for more information.
> Source: https://storybook.js.org/docs/api/main-config/main-config-webpack-final
---

# ArgTypes

ArgTypes specify the behavior of [args](https://storybook.js.org/docs/writing-stories/args.md). By specifying the type of an arg, you constrain the values that it can accept and provide information about args that are not explicitly set (i.e., [description](#description)).

You can also use argTypes to “annotate” args with information used by addons that make use of those args. For instance, to instruct the [controls panel](https://storybook.js.org/docs/essentials/controls.md) to render a color picker, you could specify the `'color'` [control type](#control).

The most concrete realization of argTypes is the [`ArgTypes` doc block](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md) ([`Controls`](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md) is similar). Each row in the table corresponds to a single argType and the current value of that arg.

![ArgTypes table](../_assets/api/doc-block-argtypes.png)

## Automatic argType inference

If you are using the Storybook [docs](https://storybook.js.org/docs/writing-docs.md) addon, then Storybook will infer a set of argTypes for each story based on the `component` specified in the [meta (or default export)](https://storybook.js.org/docs/writing-stories/index.md#default-export) of the CSF file.

To do so, Storybook uses various static analysis tools depending on your framework.

| Framework     | Static analysis tool                                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| React         | [react-docgen](https://github.com/reactjs/react-docgen) (default) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) |
| Vue           | [vue-docgen-api](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api)                                                 |
| Angular       | [compodoc](https://compodoc.app/)                                                                                                                       |
| WebComponents | [custom-element.json](https://github.com/webcomponents/custom-elements-json)                                                                            |
| Ember         | [YUI doc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components)                                                            |

The data structure of `argTypes` is designed to match the output of the these tools. Properties specified manually will override what is inferred.

## Manually specifying argTypes

For most Storybook projects, argTypes are [automatically inferred](#automatic-argtype-inference) from your components. Any argTypes specified manually will override the inferred values.

ArgTypes are most often specified at the component level, in the [meta (or default export)](https://storybook.js.org/docs/writing-stories/index.md#default-export) of the CSF file:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  argTypes: {
    // 👇 All Button stories expect a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  argTypes: {
    // 👇 All Button stories expect a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
});
```

They can apply to all stories when specified at the project (global) level, in the `preview.*` configuration file:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview = {
  argTypes: {
    // 👇 All stories expect a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
} satisfies Preview;

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  argTypes: {
    // 👇 All stories expect a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
});
```

Or they can apply only to a [specific story](https://storybook.js.org/docs/writing-stories/index.md#defining-stories):

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Basic: Story = {
  argTypes: {
    // 👇 This story expects a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
} satisfies Story;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Basic = meta.story({
  argTypes: {
    // 👇 This story expects a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
});
```

## `argTypes`

Type:

```ts
{
  [key: string]: {
    control?: ControlType | { type: ControlType; /* See below for more */ } | false;
    description?: string;
    if?: Conditional;
    mapping?: { [key: string]: { [option: string]: any } };
    name?: string;
    options?: string[];
    table?: {
      category?: string;
      defaultValue?: { summary: string; detail?: string };
      disable?: boolean;
      subcategory?: string;
      type?: { summary?: string; detail?: string };
    },
    type?: SBType | SBScalarType['name'];
  }
}
```

You configure argTypes using an object with keys matching the name of args. The value of each key is an object with the following properties:

### `control`

Type:

```ts
| ControlType
| {
    type: ControlType,
    accept?: string;
    labels?: { [option: string]: string };
    max?: number;
    min?: number;
    presetColors?: string[];
    step?: number;
  }
| false
```

Default:

1. `'select'`, if [`options`](#options) are specified
2. Else, inferred from [`type`](#type)
3. Else, `'object'`

Specify the behavior of the [controls panel](https://storybook.js.org/docs/essentials/controls.md) for the arg. If you specify a string, it's used as the [`type`](#controltype) of the control. If you specify an object, you can provide additional configuration. Specifying `false` will prevent the control from rendering.

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    value: {
      control: {
        type: 'number',
        min: 0,
        max: 100,
        step: 10,
      },
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    value: {
      control: {
        type: 'number',
        min: 0,
        max: 100,
        step: 10,
      },
    },
  },
});
```

#### `control.type`

Type: `ControlType | null`

Default: [Inferred](#automatic-argtype-inference); `'select'`, if [`options`](#options) are specified; falling back to `'object'`

Specifies the type of control used to change the arg value with the [controls panel](https://storybook.js.org/docs/essentials/controls.md). Here are the available types, `ControlType`, grouped by the type of data they handle:

| Data type   | ControlType      | Description                                                                                                                                                                             |
| ----------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **array**   | `'object'`       | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.<br /> `{ control: 'object' }`                                                          |
| **boolean** | `'boolean'`      | Provides a toggle for switching between possible states.<br /> `{ control: 'boolean' }`                                                                                                 |
| **enum**    | `'check'`        | Provides a set of stacked checkboxes for selecting multiple options.<br /> `{ control: 'check', options: ['email', 'phone', 'mail'] }`                                                  |
|             | `'inline-check'` | Provides a set of inlined checkboxes for selecting multiple options.<br /> `{ control: 'inline-check', options: ['email', 'phone', 'mail'] }`                                           |
|             | `'radio'`        | Provides a set of stacked radio buttons based on the available options.<br /> `{ control: 'radio', options: ['email', 'phone', 'mail'] }`                                               |
|             | `'inline-radio'` | Provides a set of inlined radio buttons based on the available options.<br /> `{ control: 'inline-radio', options: ['email', 'phone', 'mail'] }`                                        |
|             | `'select'`       | Provides a select to choose a single value from the options.<br /> `{ control: 'select', options: [20, 30, 40, 50] }`                                                                   |
|             | `'multi-select'` | Provides a select to choose multiple values from the options.<br /> `{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }`                                                 |
| **number**  | `'number'`       | Provides a numeric input to include the range of all possible values.<br /> `{ control: { type: 'number', min:1, max:30, step: 2 } }`                                                   |
|             | `'range'`        | Provides a range slider to include all possible values.<br /> `{ control: { type: 'range', min: 1, max: 30, step: 3 } }`                                                                |
| **object**  | `'file'`         | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.<br /> `{ control: { type: 'file', accept: '.png' } }`                     |
|             | `'object'`       | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.<br /> `{ control: 'object' }`                                                              |
| **string**  | `'color'`        | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.<br /> `{ control: { type: 'color', presetColors: ['red', 'green']} }` |
|             | `'date'`         | Provides a datepicker to choose a date.<br /> `{ control: 'date' }`                                                                                                                     |
|             | `'text'`         | Provides a freeform text input.<br /> `{ control: 'text' }`                                                                                                                             |

The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object.

#### `control.accept`

Type: `string`

When `type` is `'file'`, you can specify the file types that are accepted. The value should be a string of comma-separated MIME types.

#### `control.labels`

Type: `{ [option: string]: string }`

Map [`options`](#options) to labels. `labels` doesn't have to be exhaustive. If an option is not in the object's keys, it's used verbatim.

#### `control.max`

Type: `number`

When `type` is `'number'` or `'range'`, sets the maximum allowed value.

#### `control.min`

Type: `number`

When `type` is `'number'` or `'range'`, sets the minimum allowed value.

#### `control.presetColors`

Type: `string[]`

When `type` is `'color'`, defines the set of colors that are available in addition to the general color picker. The values in the array should be valid CSS color values.

#### `control.step`

Type: `number`

When `type` is `'number'` or `'range'`, sets the granularity allowed when incrementing/decrementing the value.

### `description`

Type: `string`

Default: [Inferred](#automatic-argtype-inference)

Describe the arg. (If you intend to describe the type of the arg, you should use [`table.type`](#tabletype), instead.)

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    value: {
      description: 'The value of the slider',
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    value: {
      description: 'The value of the slider',
    },
  },
});
```

### `if`

Type:

```ts
{
  [predicateType: 'arg' | 'global']: string;
  eq?: any;
  exists?: boolean;
  neq?: any;
  truthy?: boolean;
}
```

Conditionally render an argType based on the value of another [arg](https://storybook.js.org/docs/writing-stories/args.md) or [global](https://storybook.js.org/docs/essentials/toolbars-and-globals.md).

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    parent: { control: 'select', options: ['one', 'two', 'three'] },

    // 👇 Only shown when `parent` arg exists
    parentExists: { if: { arg: 'parent', exists: true } },

    // 👇 Only shown when `parent` arg does not exist
    parentDoesNotExist: { if: { arg: 'parent', exists: false } },

    // 👇 Only shown when `parent` arg value is truthy
    parentIsTruthy: { if: { arg: 'parent' } },
    parentIsTruthyVerbose: { if: { arg: 'parent', truthy: true } },

    // 👇 Only shown when `parent` arg value is not truthy
    parentIsNotTruthy: { if: { arg: 'parent', truthy: false } },

    // 👇 Only shown when `parent` arg value is 'three'
    parentIsEqToValue: { if: { arg: 'parent', eq: 'three' } },

    // 👇 Only shown when `parent` arg value is not 'three'
    parentIsNotEqToValue: { if: { arg: 'parent', neq: 'three' } },

    // Each of the above can also be conditional on the value of a globalType, e.g.:

    // 👇 Only shown when `theme` global exists
    parentExists: { if: { global: 'theme', exists: true } },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    parent: { control: 'select', options: ['one', 'two', 'three'] },

    // 👇 Only shown when `parent` arg exists
    parentExists: { if: { arg: 'parent', exists: true } },

    // 👇 Only shown when `parent` arg does not exist
    parentDoesNotExist: { if: { arg: 'parent', exists: false } },

    // 👇 Only shown when `parent` arg value is truthy
    parentIsTruthy: { if: { arg: 'parent' } },
    parentIsTruthyVerbose: { if: { arg: 'parent', truthy: true } },

    // 👇 Only shown when `parent` arg value is not truthy
    parentIsNotTruthy: { if: { arg: 'parent', truthy: false } },

    // 👇 Only shown when `parent` arg value is 'three'
    parentIsEqToValue: { if: { arg: 'parent', eq: 'three' } },

    // 👇 Only shown when `parent` arg value is not 'three'
    parentIsNotEqToValue: { if: { arg: 'parent', neq: 'three' } },

    // Each of the above can also be conditional on the value of a globalType, e.g.:

    // 👇 Only shown when `theme` global exists
    parentExists: { if: { global: 'theme', exists: true } },
  },
});
```

### `mapping`

Type: `{ [key: string]: { [option: string]: any } }`

Map [`options`](#options) to values.

When dealing with non-primitive values, you'll notice that you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deeplink to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls panel) and the preview (your story).

`mapping` doesn't have to be exhaustive. If the currently selected option is not listed, it's used verbatim. Can be used with [`control.labels`](#labels).

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    label: {
      control: { type: 'select' },
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    label: {
      control: { type: 'select' },
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
});
```

### `name`

Type: `string`

The `argTypes` object uses the name of the arg as the key. By default, that key is used when displaying the argType in Storybook. You can override the displayed name by specifying a `name` property.

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    actualArgName: {
      name: 'Friendly name',
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    actualArgName: {
      name: 'Friendly name',
    },
  },
});
```

Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed.

For this reason, the `name` property is best used when defining an `argType` that is only used for documentation purposes and not an actual property of the component. For example, when [providing argTypes for each property of an object](https://stackblitz.com/edit/github-uplqzp?file=src/stories/Button.stories.tsx).

### `options`

Type: `string[]`

Default: [Inferred](#automatic-argtype-inference)

If the arg accepts a finite set of values, you can specify them with `options`. If those values are [complex](https://storybook.js.org/docs/essentials/controls.md#dealing-with-complex-values), like JSX elements, you can use [`mapping`](#mapping) to map them to string values. You can use [`control.labels`](#labels) to provide custom labels for the options.

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    icon: {
      options: ['arrow-up', 'arrow-down', 'loading'],
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    icon: {
      options: ['arrow-up', 'arrow-down', 'loading'],
    },
  },
});
```

### `table`

Type:

```ts
{
  category?: string;
  defaultValue?: {
    detail?: string;
    summary: string;
  };
  disable?: boolean;
  subcategory?: string;
  type?: {
    detail?: string;
    summary: string;
  };
}
```

Default: [Inferred](#automatic-argtype-inference)

Specify how the arg is documented in the [`ArgTypes` doc block](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md), [`Controls` doc block](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md), and [Controls panel](https://storybook.js.org/docs/essentials/controls.md).

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    value: {
      table: {
        defaultValue: { summary: 0 },
        type: { summary: 'number' },
      },
    },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    value: {
      table: {
        defaultValue: { summary: 0 },
        type: { summary: 'number' },
      },
    },
  },
});
```

#### `table.category`

Type: `string`

Default: [Inferred](#automatic-argtype-inference), in some frameworks

Display the argType under a category heading, with the label specified by `category`.

#### `table.defaultValue`

Type: `{ detail?: string; summary: string }`

Default: [Inferred](#automatic-argtype-inference)

The documented default value of the argType. `summary` is typically used for the value itself, while `detail` is used for additional information.

#### `table.disable`

Type: `boolean`

Set to `true` to remove the argType's row from the table.

#### `table.readonly`

Type: `boolean`

Set to `true` to indicate that the argType is read-only.

#### `table.subcategory`

Type: `string`

Display the argType under a subcategory heading (which displays under the \[`category`] heading), with the label specified by `subcategory`.

#### `table.type`

Type: `{ detail?: string; summary: string }`

Default: Inferred from [`type`](#type)

The documented type of the argType. `summary` is typically used for the type itself, while `detail` is used for additional information.

If you need to specify the actual, semantic type, you should use [`type`](#type), instead.

### `type`

Type: `'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType`

The full type of `SBType` is:

<details>
<summary>SBType</summary>

```ts
interface SBBaseType {
  required?: boolean;
  raw?: string;
}

type SBScalarType = SBBaseType & {
  name: 'boolean' | 'string' | 'number' | 'function' | 'symbol';
};

type SBArrayType = SBBaseType & {
  name: 'array';
  value: SBType;
};
type SBObjectType = SBBaseType & {
  name: 'object';
  value: Record<string, SBType>;
};
type SBEnumType = SBBaseType & {
  name: 'enum';
  value: (string | number)[];
};
type SBIntersectionType = SBBaseType & {
  name: 'intersection';
  value: SBType[];
};
type SBUnionType = SBBaseType & {
  name: 'union';
  value: SBType[];
};
type SBOtherType = SBBaseType & {
  name: 'other';
  value: string;
};

type SBType =
  | SBScalarType
  | SBEnumType
  | SBArrayType
  | SBObjectType
  | SBIntersectionType
  | SBUnionType
  | SBOtherType;
```

</details>

Default: [Inferred](#automatic-argtype-inference)

Specifies the semantic type of the argType. When an argType is [inferred](#automatic-argtype-inference), the information from the various tools is summarized in this property, which is then used to infer other properties, like [`control`](#control) and [`table.type`](#tabletype).

If you only need to specify the documented type, you should use [`table.type`](#tabletype), instead.

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    value: { type: 'number' },
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    value: { type: 'number' },
  },
});
```

### `defaultValue`

(⛔️ **Deprecated**)

Type: `any`

Define the default value of the argType. Deprecated in favor of defining the [`arg`](https://storybook.js.org/docs/writing-stories/args.md) value directly.

```ts
// Example.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Example,
  argTypes: {
    value: {
      // ❌ Deprecated
      defaultValue: 0,
    },
  },
  // ✅ Do this instead
  args: {
    value: 0,
  },
} satisfies Meta<typeof Example>;

export default meta;
```

```ts
// Example.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Example,
  argTypes: {
    value: {
      // ❌ Deprecated
      defaultValue: 0,
    },
  },
  // ✅ Do this instead
  args: {
    value: 0,
  },
});
```
> Source: https://storybook.js.org/docs/api/arg-types
---

# Parameters

Parameters are static metadata used to configure your [stories](https://storybook.js.org/docs/get-started/whats-a-story.md) and [addons](https://storybook.js.org/docs/addons.md) in Storybook. They are specified at the story, meta (component), project (global) levels.

## Story parameters

Parameters specified at the story level apply to that story only. They are defined in the `parameters` property of the story (named export):

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Primary: Story = {
  // 👇 Story-level parameters
  parameters: {
    backgrounds: {
      options: {
        red: { name: 'Red', value: '#f00' },
        green: { name: 'Green', value: '#0f0' },
        blue: { name: 'Blue', value: '#00f' },
      },
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Primary = meta.story({
  // 👇 Story-level parameters
  parameters: {
    backgrounds: {
      options: {
        red: { name: 'Red', value: '#f00' },
        green: { name: 'Green', value: '#0f0' },
        blue: { name: 'Blue', value: '#00f' },
      },
    },
  },
});
```

Parameters specified at the story level will [override](#parameter-inheritance) those specified at the project level and meta (component) level.

## Meta parameters

Parameter's specified in a [CSF](https://storybook.js.org/docs/writing-stories/index.md#component-story-format) file's meta configuration apply to all stories in that file. They are defined in the `parameters` property of the meta (or default export):

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      options: {},
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      options: {},
    },
  },
});
```

Parameters specified at the meta (component) level will [override](#parameter-inheritance) those specified at the project level.

## Project parameters

Parameters specified at the project (global) level apply to **all stories** in your Storybook. They are defined in the `parameters` property of the meta (or default export) in your `.storybook/preview.*` file:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#fff' },
        dark: { name: 'Dark', value: '#333' },
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#fff' },
        dark: { name: 'Dark', value: '#333' },
      },
    },
  },
});
```

## Available parameters

Storybook only accepts a few parameters directly.

### `layout`

Type: `'centered' | 'fullscreen' | 'padded'`

Default: `'padded'`

Specifies how the canvas should [lay out the story](https://storybook.js.org/docs/configure/story-layout.md).

- **centered**: Center the story within the canvas
- **padded**: (default) Add padding to the story
- **fullscreen**: Show the story as-is, without padding

### `options`

Type:

```ts
{
  storySort?: StorySortConfig | StorySortFn;
}
```

The `options` parameter can _only_ be applied at the [project level](#project-parameters).

#### `options.storySort`

Type: `StorySortConfig | StorySortFn`

```ts
type StorySortConfig = {
  includeNames?: boolean;
  locales?: string;
  method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom';
  order?: string[];
};

type Story = {
  id: string;
  importPath: string;
  name: string;
  title: string;
};

type StorySortFn = (a: Story, b: Story) => number;
```

Specifies the order in which stories are displayed in the Storybook UI.

When specifying a configuration object, the following options are available:

- **includeNames**: Whether to include the story name in the sorting algorithm. Defaults to `false`.
- **locales**: The locale to use when sorting stories. Defaults to your system locale.
- **method**: The sorting method to use. Defaults to `alphabetical`.
  - **alphabetical**: Sort stories alphabetically by name.
  - **alphabetical-by-kind**: Sort stories alphabetically by kind, then by name.
  - **custom**: Use a custom sorting function.
- **order**: Stories in the specified order will be displayed first, in the order specified. All other stories will be displayed after, in alphabetical order. The order array can accept a nested array to sort 2nd-level story kinds, e.g. `['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']`.

When specifying a custom sorting function, the function behaves like a typical JavaScript sorting function. It accepts two stories to compare and returns a number. For example:

```js
(a, b) => (a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }));
```

See [the guide](https://storybook.js.org/docs/writing-stories/naming-components-and-hierarchy.md#sorting-stories) for usage examples.

### `test`

Type:

```ts
{
  clearMocks?: boolean;
  mockReset?: boolean;
  restoreMocks?: boolean;
  dangerouslyIgnoreUnhandledErrors?: boolean;
}
```

#### `clearMocks`

Type: `boolean`

Default: `false`

[Similar to Vitest](https://vitest.dev/config/#clearmocks), it will call `.mockClear()` on all spies created with `fn()` from `storybook/test` when a story unmounts. This will clear mock history, but not reset its implementation to the default one.

#### `mockReset`

Type: `boolean`

Default: `false`

[Similar to Vitest](https://vitest.dev/config/#mockreset), it will call `.mockReset()` on all spies created with `fn()` from `storybook/test` when a story unmounts. This will clear mock history and reset its implementation to an empty function (will return `undefined`).

#### `restoreMocks`

Type: `boolean`

Default: `true`

[Similar to Vitest](https://vitest.dev/config/#restoremocks), it will call `.restoreMocks()` on all spies created with `fn()` from `storybook/test` when a story unmounts. This will clear mock history and reset its implementation to the original one.

#### `dangerouslyIgnoreUnhandledErrors`

Type: `boolean`

Default: `false`

Unhandled errors might cause false positive assertions. Setting this to `true` will prevent the [play function](https://storybook.js.org/docs/writing-stories/play-function.md) from failing and showing a warning when unhandled errors are thrown during execution.

---

### Essentials

All other parameters are contributed by features. The [essential feature's](https://storybook.js.org/docs/essentials.md) parameters are documented on their individual pages:

- [Actions](https://storybook.js.org/docs/essentials/actions.md#parameters)
- [Backgrounds](https://storybook.js.org/docs/essentials/backgrounds.md#parameters)
- [Controls](https://storybook.js.org/docs/essentials/controls.md#parameters)
- [Highlight](https://storybook.js.org/docs/essentials/highlight.md#parameters)
- [Measure & Outline](https://storybook.js.org/docs/essentials/measure-and-outline.md#parameters)
- [Viewport](https://storybook.js.org/docs/essentials/viewport.md#parameters)

## Parameter inheritance

No matter where they're specified, parameters are ultimately applied to a single story. Parameters specified at the project (global) level are applied to every story in that project. Those specified at the meta (component) level are applied to every story associated with that meta. And parameters specified for a story only apply to that story.

When specifying parameters, they are merged together in order of increasing specificity:

1. Project (global) parameters
2. Meta (component) parameters
3. Story parameters

Parameters are **merged**, so objects are deep-merged, but arrays and other properties are overwritten.

In other words, the following specifications of parameters:

```js title=".storybook/preview.js"
const preview = {
  // 👇 Project-level parameters
  parameters: {
    layout: 'centered',
    demo: {
      demoProperty: 'a',
      demoArray: [1, 2],
    },
  },
  // ...
};
export default preview;
```

```js title="Dialog.stories.js|ts"
const meta = {
  component: Dialog,
  // 👇 Meta-level parameters
  parameters: {
    layout: 'fullscreen',
    demo: {
      demoProperty: 'b',
      anotherDemoProperty: 'b',
    },
  },
};
export default meta;

// (no additional parameters specified)
export const Basic = {};

export const LargeScreen = {
  // 👇 Story-level parameters
  parameters: {
    layout: 'padded',
    demo: {
      demoArray: [3, 4],
    },
  },
};
```

Will result in the following parameter values applied to each story:

```js
// Applied story parameters

// For the Basic story:
{
  layout: 'fullscreen',
  demo: {
    demoProperty: 'b',
    anotherDemoProperty: 'b',
    demoArray: [1, 2],
  },
}

// For the LargeScreen story:
{
  layout: 'padded',
  demo: {
    demoProperty: 'b',
    anotherDemoProperty: 'b',
    demoArray: [3, 4],
  },
}
```
> Source: https://storybook.js.org/docs/api/parameters
---

# ArgTypes

The `ArgTypes` block can be used to show a static table of [arg types](https://storybook.js.org/docs/api/arg-types.md) for a given component, as a way to document its interface.

If you’re looking for a dynamic table that shows a story’s current arg values for a story and supports users changing them, see the [`Controls`](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md) block instead.

![Screenshot of ArgTypes block](../../_assets/api/doc-block-argtypes.png)

```mdx title="ButtonDocs.mdx"

```

## ArgTypes

```js

```

<details>
<summary>Configuring with props <strong>and</strong> parameters</summary>

ℹ️ Like most blocks, the `ArgTypes` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in the block's namespace, `parameters.docs.argTypes`.

The following `exclude` configurations are equivalent:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  parameters: {
    docs: {
      argTypes: { exclude: ['style'] },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    docs: {
      argTypes: { exclude: ['style'] },
    },
  },
});
```

```mdx title="ButtonDocs.mdx"

```

The example above applied the parameter at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) or [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level.

</details>

### `exclude`

Type: `string[] | RegExp`

Default: `parameters.docs.argTypes.exclude`

Specifies which arg types to exclude from the args table. Any arg types whose names match the regex or are part of the array will be left out.

### `include`

Type: `string[] | RegExp`

Default: `parameters.docs.argTypes.include`

Specifies which arg types to include in the args table. Any arg types whose names don’t match the regex or are not part of the array will be left out.

### `of`

Type: Story export or CSF file exports

Specifies which story to get the arg types from. If a CSF file exports is provided, it will use the primary (first) story in the file.

### `sort`

Type: `'none' | 'alpha' | 'requiredFirst'`

Default: `parameters.docs.argTypes.sort` or `'none'`

Specifies how the arg types are sorted.

- **none**: Unsorted, displayed in the same order the arg types are processed in
- **alpha**: Sorted alphabetically, by the arg type's name
- **requiredFirst**: Same as `alpha`, with any required arg types displayed first
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes
---

# Canvas

The `Canvas` block is a wrapper around a [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md), featuring a toolbar that allows you to interact with its content while automatically providing the required [`Source`](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md) snippets.

![Screenshot of Canvas block](../../_assets/api/doc-block-canvas.png)

When using the Canvas block in MDX, it references a story with the `of` prop:

```mdx title="ButtonDocs.mdx"

```

In previous versions of Storybook it was possible to pass in arbitrary components as children to `Canvas`. That is deprecated and the `Canvas` block now only supports a single story.

## Canvas

```js

```

<details>
<summary>Configuring with props <strong>and</strong> parameters</summary>

ℹ️ Like most blocks, the `Canvas` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in the block's namespace, `parameters.docs.canvas`.

The following `sourceState` configurations are equivalent:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Basic: Story = {
  parameters: {
    docs: {
      canvas: { sourceState: 'shown' },
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Basic = meta.story({
  parameters: {
    docs: {
      canvas: { sourceState: 'shown' },
    },
  },
});
```

```mdx title="ButtonDocs.mdx"

```

The example above applied the parameter at the [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) (or meta) level or [project](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) level.

</details>

### `additionalActions`

Type:

```ts
Array<{
  title: string | JSX.Element;
  className?: string;
  onClick: () => void;
  disabled?: boolean;
}>;
```

Default: `parameters.docs.canvas.additionalActions`

Provides any additional custom actions to show in the bottom right corner. These are simple buttons that do anything you specify in the `onClick` function.

```mdx title="ButtonDocs.mdx"

<Canvas
  additionalActions={[
    {
      title: 'Open in GitHub',
      onClick: () => {
        window.open(
          'https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/examples/Button.stories.tsx',
          '_blank',
        );
      },
    },
  ]}
  of={ButtonStories.Primary}
/>
```

### `className`

Type: `string`

Default: `parameters.docs.canvas.className`

Provides HTML class(es) to the preview element, for custom styling.

### `layout`

Type: `'centered' | 'fullscreen' | 'padded'`

Default: `parameters.layout` or `parameters.docs.canvas.layout` or `'padded'`

Specifies how the canvas should layout the story.

- **centered**: Center the story within the canvas
- **padded**: (default) Add padding to the story
- **fullscreen**: Show the story as-is, without padding

In addition to the `parameters.docs.canvas.layout` property or the `layout` prop, the `Canvas` block will respect the `parameters.layout` value that defines [how a story is laid out](https://storybook.js.org/docs/configure/story-layout.md) in the regular story view.

### `meta`

Type: CSF file exports

Specifies the CSF file to which the story is associated.

You can render a story from a CSF file that you haven’t attached to the MDX file (via `Meta`) by using the `meta` prop. Pass the **full set of exports** from the CSF file (not the default export!).

```mdx title="ButtonDocs.mdx"

```

### `of`

Type: Story export

Specifies which story's source is displayed.

### `source`

Type: `SourceProps['code'] | SourceProps['format'] | SourceProps['language'] | SourceProps['type']`

Specifies the props passed to the inner `Source` block. For more information, see the `Source` Doc Block [documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md).

The dark prop is ignored, as the `Source` block is always rendered in dark mode when shown as part of a `Canvas` block.

### `sourceState`

Type: `'hidden' | 'shown' | 'none'`

Default: `parameters.docs.canvas.sourceState` or `'hidden'`

Specifies the initial state of the source panel.

- **hidden**: the source panel is hidden by default
- **shown**: the source panel is shown by default
- **none**: the source panel is not available and the button to show it is not rendered

### `story`

Type: `StoryProps['inline'] | StoryProps['height'] | StoryProps['autoplay']`

Specifies the props passed to the inner `Story` block. For more information, see the `Story` Doc Block [documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md).

### `withToolbar`

Type: `boolean`

Default: `parameters.docs.canvas.withToolbar`

Determines whether to render a toolbar containing tools to interact with the story.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas
---

# ColorPalette

The `ColorPalette` block allows you to document all color-related items (e.g., swatches) used throughout your project.

![Screenshot of ColorPalette and ColorItem blocks](../../_assets/api/doc-block-colorpalette.png)

```mdx title="Colors.mdx"

  
  
  
  
  
  

```

## ColorPalette

```js

```

`ColorPalette` is configured with the following props:

### `children`

Type: `React.ReactNode`

`ColorPalette` expects only `ColorItem` children.

## ColorItem

```js

```

`ColorItem` is configured with the following props:

### `colors`

(**Required**)

Type: `string[] | { [key: string]: string }`

Provides the list of colors to be displayed. Accepts any valid CSS color format (hex, RGB, HSL, etc.). When an object is provided, the keys will be displayed above the values. Additionally, it supports gradients such as 'linear-gradient(to right, white, black)' or 'linear-gradient(65deg, white, black)', etc.

### `subtitle`

(**Required**)

Type: `string`

Provides an additional description of the color.

### `title`

(**Required**)

Type: `string`

Sets the name of the color to be displayed.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-colorpalette
---

# Controls

The `Controls` block can be used to show a dynamic table of args for a given story, as a way to document its interface, and to allow you to change the args for a (separately) rendered story (via the [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md) or [`Canvas`](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) blocks).

If you’re looking for a static table that shows a component's arg types with no controls, see the [`ArgTypes`](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md) block instead.

![Screenshot of Controls block](../../_assets/api/doc-block-controls.png)

```mdx title="ButtonDocs.mdx"

```

The Controls doc block will only have functioning UI controls if you haven't turned off inline stories with the [`inline`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md#inline) configuration option.

## Controls

```js

```

<details>
<summary>Configuring with props <strong>and</strong> parameters</summary>

ℹ️ Like most blocks, the `Controls` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in the block's namespace, `parameters.docs.controls`.

The following `exclude` configurations are equivalent:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: Button,
  parameters: {
    docs: {
      controls: { exclude: ['style'] },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
  parameters: {
    docs: {
      controls: { exclude: ['style'] },
    },
  },
});
```

```mdx title="ButtonDocs.mdx"

```

The example above applied the parameter at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) or [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level.

</details>

This API configures the `Controls` blocks used within docs pages. To configure the Controls panel, see the [feature documentation](https://storybook.js.org/docs/essentials/controls.md). To configure individual controls, specify [argTypes](https://storybook.js.org/docs/api/arg-types.md#control) for each.

### `exclude`

Type: `string[] | RegExp`

Default: `parameters.docs.controls.exclude`

Specifies which controls to exclude from the args table. Any controls whose names match the regex or are part of the array will be left out.

### `include`

Type: `string[] | RegExp`

Default: `parameters.docs.controls.include`

Specifies which controls to include in the args table. Any controls whose names don't match the regex or are not part of the array will be left out.

### `of`

Type: Story export or CSF file exports

Specifies which story to get the controls from. If a CSF file exports is provided, it will use the primary (first) story in the file.

### `sort`

Type: `'none' | 'alpha' | 'requiredFirst'`

Default: `parameters.docs.controls.sort` or `'none'`

Specifies how the controls are sorted.

- **none**: Unsorted, displayed in the same order the controls are processed in
- **alpha**: Sorted alphabetically, by the arg type's name
- **requiredFirst**: Same as `alpha`, with any required controls displayed first
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-controls
---

# Description

The `Description` block displays the description for a component, story, or meta, obtained from their respective JSDoc comments.

![Screenshot of Description block](../../_assets/api/doc-block-title-subtitle-description.png)

```mdx title="ButtonDocs.mdx"

```

## Description

```js

```

`Description` is configured with the following props:

### `of`

Type: Story export or CSF file exports

Specifies where to pull the description from. It can either point to a story or a meta, depending on which description you want to show.

Descriptions are pulled from the JSDoc comments or parameters, and they are rendered as markdown. See [Writing descriptions](#writing-descriptions) for more details.

## Writing descriptions

There are multiple places to write the description of a component/story, depending on what you want to achieve. Descriptions can be written at the story level to describe each story of a component, or they can be written at the meta or component level to describe the component in general.

Descriptions can be written as [JSDoc comments](https://jsdoc.app/about-getting-started.html) above stories, meta, or components. Alternatively they can also be specified in [`parameters`](https://storybook.js.org/docs/writing-stories/parameters.md). To describe a story via parameters instead of comments, add it to `parameters.docs.description.story`; to describe meta/component, add it to `parameters.docs.description.component`.

We recommend using JSDoc comments for descriptions, and only use the `parameters.docs.description.X` properties in situations where comments are not possible to write for some reason, or where you want the description shown in Storybook to be different from the comments. Comments provide a better writing experience as you don’t have to worry about indentation, and they are more discoverable for other developers that are exploring the story/component sources.

When documenting a story, reference a story export in the `of` prop (see below) and the Description block will look for descriptions in the following order:

1. `parameters.docs.description.story` in the story
2. JSDoc comments above the story

When documenting a component, reference a meta export in the `of` prop (see below) and the Description block will look for descriptions in the following order:

1. `parameters.docs.description.component` in the meta
2. JSDoc comments above the meta
3. JSDoc comments above the component

This flow gives you powerful ways to override the description for each scenario. Take the following example:

```jsx title="Button.jsx"
/**
 * The Button component shows a button
 */
export const Button = () => <button>Click me</button>;
```

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

/**
 * Button stories
 * These stories showcase the button
 */
const meta = {
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'Another description, overriding the comments',
      },
    },
  },
} satisfies Meta<typeof Button>;

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

/**
 * Primary Button
 * This is the primary button
 */
export const Primary: Story = {
  parameters: {
    docs: {
      description: {
        story: 'Another description on the story, overriding the comments',
      },
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

/**
 * Button stories
 * These stories showcase the button
 */
const meta = preview.meta({
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'Another description, overriding the comments',
      },
    },
  },
});

/**
 * Primary Button
 * This is the primary button
 */
export const Primary = meta.story({
  parameters: {
    docs: {
      description: {
        story: 'Another description on the story, overriding the comments',
      },
    },
  },
});
```

```mdx title="ButtonDocs.mdx"

```
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-description
---

# IconGallery

The `IconGallery` block enables you to easily document React icon components associated with your project, displayed in a neat grid.

![Screenshot of IconGallery and IconItem blocks](../../_assets/api/doc-block-icongallery.png)

## Documenting icons

To document a set of icons, use the `IconGallery` block to display them in a grid. Each icon is wrapped in an `IconItem` block, enabling you to specify its properties, such as the name and the icon itself.

```mdx title="Iconography.mdx"

# Iconography

  
    
  
  
    
  
  
    
  
  
    
  
  
    
  
  
    
  
  
    
  
  
    
  
  
    
  
  
    
  

```

### Automate icon documentation

If you're working on a project that contains a large number of icons that you want to document, you can extend the `IconGallery` block, wrap `IconItem` in a loop, and iterate over the icons you want to document, including their properties. For example:

```mdx title="Iconography.mdx"

# Iconography

  {Object.keys(icons).map((icon) => (
    
      
    
  ))}

```

## IconGallery

```js

```

`IconGallery` is configured with the following props:

### `children`

Type: `React.ReactNode`

`IconGallery` expects only `IconItem` children.

## IconItem

```js

```

`IconItem` is configured with the following props:

### `name`

(**Required**)

Type: `string`

Sets the name of the icon.

### `children`

Type: `React.ReactNode`

Provides the icon to be displayed.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-icongallery
---

# Markdown

The `Markdown` block allows you to import and include plain markdown in your MDX files.

![Screenshot of Markdown block](../../_assets/api/doc-block-markdown.png)

When importing markdown files, it’s important to use the `?raw` suffix on the import path to ensure the content is imported as-is, and isn’t being evaluated:

````md title="README.md"
# Button

Primary UI component for user interaction

```js

```
````

```mdx title="Header.mdx"
// DON'T do this, will error

// DO this, will work

# A header

{ReadMe}
```

## Markdown

```js

```

`Markdown` is configured with the following props:

### `children`

Type: `string`

Provides the markdown-formatted string to parse and display.

### `options`

Specifies the options passed to the underlying [`markdown-to-jsx` library](https://github.com/probablyup/markdown-to-jsx/blob/main/README.md).

## Why not import markdown directly?

From a purely technical standpoint, we could include the imported markdown directly in the MDX file like this:

```mdx

# A header

{ReadMe}
```

However, there are small syntactical differences between plain markdown and MDX2. MDX2 is more strict and will interpret certain content as JSX expressions. Here’s an example of a perfectly valid markdown file, that would break if it was handled directly by MDX2:

```md
# A header

{ this is valid in a plain markdown file, but MDX2 will try to evaluate this as an expression }

```

Furthermore, MDX2 wraps all strings on newlines in `p` tags or similar, meaning that content would render differently between a plain `.md` file and an `.mdx` file.

```md
# A header

<div>
  Some text
</div>

The example above will remain as-is in plain markdown, but MDX2 will compile it to:

# A header

<div>
  <p>Some text</p>
</div>
```
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-markdown
---

# Meta

The `Meta` block is used to [attach](#attached-vs-unattached) a custom MDX docs page alongside a component’s list of stories. It doesn’t render any content, but serves two purposes in an MDX file:

- Attaches the MDX file to a component and its stories, or
- Controls the location of the unattached docs entry in the sidebar.

```mdx title="ButtonDocs.mdx"

```

The Meta block doesn’t render anything visible.

## Meta

```js

```

`Meta` is configured with the following props:

### `isTemplate`

Type: `boolean`

Determines whether the MDX file serves as an [automatic docs template](https://storybook.js.org/docs/writing-docs/autodocs.md#with-mdx). When true, the MDX file is not indexed as it normally would be.

### `name`

Type: `string`

Sets the name of the [attached](#attached-vs-unattached) doc entry. You can attach more than one MDX file to the same component in the sidebar by setting different names for each file's `Meta`.

```mdx title="Component.mdx"

```

### `of`

Type: CSF file exports

Specifies which CSF file is [attached](#attached-vs-unattached) to this MDX file. Pass the **full set of exports** from the CSF file (not the default export!).

```mdx title="ButtonDocs.mdx"

```

Attaching an MDX file to a component’s stories with the `of` prop serves two purposes:

1. Ensures the MDX content appears in the sidebar inside the component’s story list. By default, it will be named whatever the `docs.defaultName` (which defaults to `"Docs"`) option is set to in `main.js`. But this can be overridden with the [`name` prop](#name).
2. Attaches the component and its stories to the MDX file, allowing you to use other doc blocks in “attached” mode (for instance to use the `Stories` block).

The `of` prop is optional. If you don’t want to attach a specific CSF file to this MDX file, you can either use the `title` prop to control the location, or emit `Meta` entirely, and let [autotitle](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#csf-30-auto-titles) decide where it goes.

### `title`

Type: `string`

Sets the title of an [unattached](#attached-vs-unattached) MDX file.

```mdx title="Introduction.mdx"

```

If you want to change the sorting of the docs entry with the component’s stories, use [Story Sorting](https://storybook.js.org/docs/writing-stories/naming-components-and-hierarchy.md#sorting-stories), or add specific MDX files to your `stories` field in `main.js` in order.

## Attached vs. unattached

In Storybook, a docs entry (MDX file) is "attached" when it is associated with a stories file, via `Meta`'s [`of` prop](#of). Attached docs entries display next to the stories list under the component in the sidebar.

"Unattached" docs entries are not associated with a stories file and can be displayed anywhere in the sidebar via `Meta`'s [`title` prop](#title).
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-meta
---

# Primary

The `Primary` block displays the primary (first defined in the stories file) story, in a [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md) block. It is typically rendered immediately under the title in a docs entry.

![Screenshot of Primary block](../../_assets/api/doc-block-primary.png)

```mdx title="ButtonDocs.mdx"

```

## Primary

```js

```

`Primary` is configured with the following props:

### `of`

Type: CSF file exports

Specifies which CSF file is used to find the first story, which is then rendered by this block. Pass the full set of exports from the CSF file (not the default export!).
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-primary
---

# Source

The `Source` block is used to render a snippet of source code directly.

![Screenshot of Source block](../../_assets/api/doc-block-source.png)

```mdx title="ButtonDocs.mdx"

```

## Source

```js

```

<details>
<summary>Configuring with props <strong>and</strong> parameters</summary>

ℹ️ Like most blocks, the `Source` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in the block's namespace, `parameters.docs.source`.

The following `language` configurations are equivalent:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Basic: Story = {
  parameters: {
    docs: {
      source: { language: 'ts' },
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Basic = meta.story({
  parameters: {
    docs: {
      source: { language: 'tsx' },
    },
  },
});
```

```mdx title="ButtonDocs.mdx"

```

The example above applied the parameter at the [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) (or meta) level or [project](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) level.

</details>

### `code`

Type: `string`

Default: `parameters.docs.source.code`

Provides the source code to be rendered.

```mdx title="ButtonDocs.mdx"

```

### `dark`

Type: `boolean`

Default: `parameters.docs.source.dark`

Determines if the snippet is rendered in dark mode.

Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md)—like it is in [autodocs](https://storybook.js.org/docs/writing-docs/autodocs.md)—it will always use dark mode.

### `excludeDecorators`

Type: `boolean`

Default: `parameters.docs.source.excludeDecorators`

Determines if [decorators](https://storybook.js.org/docs/writing-stories/decorators.md) are rendered in the source code snippet.

### `language`

Type:

```ts
'jsextra' | 'jsx' | 'json' | 'yml' | 'md' | 'bash' | 'css' | 'html' | 'tsx' | 'typescript' | 'graphql'
```

Default: `parameters.docs.source.language` or `'jsx'`

Specifies the language used for syntax highlighting.

### `of`

Type: Story export

Specifies which story's source is rendered.

### `transform`

Type: `(code: string, storyContext: StoryContext) => string | Promise<string>`

Default: `parameters.docs.source.transform`

An async function to dynamically transform the source before being rendered, based on the original source and any story context necessary. The returned string is displayed as-is.
If both [`code`](#code) and `transform` are specified, `transform` will be ignored.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g., nextjs-vite, vue3-vite, angular, sveltekit, etc.

const preview: Preview = {
  parameters: {
    docs: {
      source: {
        transform: async (source) => {
          const prettier = await import('prettier/standalone');
          const prettierPluginBabel = await import('prettier/plugins/babel');
          const prettierPluginEstree = await import('prettier/plugins/estree');

          return prettier.format(source, {
            parser: 'babel',
            plugins: [prettierPluginBabel, prettierPluginEstree],
          });
        },
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using, e.g., nextjs, nextjs-vite, react-vite, etc.

const preview = definePreview({
  parameters: {
    docs: {
      source: {
        transform: async (source) => {
          const prettier = await import('prettier/standalone');
          const prettierPluginBabel = await import('prettier/plugins/babel');
          const prettierPluginEstree = await import('prettier/plugins/estree');

          return prettier.format(source, {
            parser: 'babel',
            plugins: [prettierPluginBabel, prettierPluginEstree],
          });
        },
      },
    },
  },
});

export default preview;
```

This example shows how to use Prettier to format all source code snippets in your documentation. The transform function is applied globally through the preview configuration, ensuring consistent code formatting across all stories.

### `type`

Type: `'auto' | 'code' | 'dynamic'`

Default: `parameters.docs.source.type` or `'auto'`

Specifies how the source code is rendered.

- **auto**: Same as **dynamic**, if the story's `render` function accepts args inputs and **dynamic** is supported by the framework in use; otherwise same as **code**
- **code**: Renders the value of [`code` prop](#code), otherwise renders static story source
- **dynamic**: Renders the story source with dynamically updated arg values

Note that dynamic snippets will only work if the story uses [`args`](https://storybook.js.org/docs/writing-stories/args.md) and the [`Story` block](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md) for that story is rendered along with the `Source` block.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-source
---

# Stories

The `Stories` block renders the full collection of stories in a stories file.

![Screenshot of Stories block](../../_assets/api/doc-block-stories.png)

```mdx title="ButtonDocs.mdx"

```

## Stories

```js

```

`Stories` is configured with the following props:

### `includePrimary`

Type: `boolean`

Default: `true`

Determines if the collection of stories includes the primary (first) story.

If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation.

### `title`

Type: `string`

Default: `'Stories'`

Sets the heading content preceding the collection of stories.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-stories
---

# Story

[Stories](https://storybook.js.org/docs/writing-stories.md) are Storybook's fundamental building blocks.

In Storybook Docs, you can render any of your stories from your CSF files in the context of an MDX file with all annotations (parameters, args, loaders, decorators, play function) applied using the `Story` block.

Typically you want to use the [`Canvas` block](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) to render a story with a surrounding border and the source block, but you can use the `Story` block to render just the story.

![Screenshot of Story block](../../_assets/api/doc-block-story.png)

```mdx title="ButtonDocs.mdx"

```

## Story

```js

```

<details>
<summary>Configuring with props <strong>and</strong> parameters</summary>

ℹ️ Like most blocks, the `Story` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) in the block's namespace, `parameters.docs.story`.

The following `autoplay` configurations are equivalent:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Basic: Story = {
  parameters: {
    docs: {
      story: { autoplay: true },
    },
  },
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Basic = meta.story({
  parameters: {
    docs: {
      story: { autoplay: true },
    },
  },
});
```

```mdx title="ButtonDocs.mdx"

```

The example above applied the parameter at the [story](https://storybook.js.org/docs/writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](https://storybook.js.org/docs/writing-stories/parameters.md#component-parameters) (or meta) level or [project](https://storybook.js.org/docs/writing-stories/parameters.md#global-parameters) level.

</details>

### `autoplay`

Type: `boolean`

Default: `parameters.docs.story.autoplay`

Determines whether a story's play function runs.

Because all stories render simultaneously in docs entries, play functions can perform arbitrary actions that can interact with each other (such as stealing focus or scrolling the screen). For that reason, by default, stories **do not run play functions in docs mode**.

However, if you know your play function is “safe” to run in docs, you can use this prop to run it automatically.

If a story uses [`mount` in its play function](https://storybook.js.org/docs/writing-tests/interaction-testing.md#run-code-before-the-component-gets-rendered), it will not render in docs unless `autoplay` is set to `true`.

### `height`

Type: `string`

Default: `parameters.docs.story.height`

Set a minimum height (note for an iframe this is the actual height) when rendering a story in an iframe or inline. This overrides `parameters.docs.story.iframeHeight` for iframes.

### `inline`

Type: `boolean`

Default: `parameters.docs.story.inline` or `true` (for [supported frameworks](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md))

Determines whether the story is rendered `inline` (in the same browser frame as the other docs content) or in an iframe.

Setting the `inline` option to false will prevent the associated [controls](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md) from updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release.

### `meta`

Type: CSF file exports

Specifies the CSF file to which the story is associated.

You can render a story from a CSF file that you haven’t attached to the MDX file (via `Meta`) by using the `meta` prop. Pass the **full set of exports** from the CSF file (not the default export!).

```mdx title="ButtonDocs.mdx"

```

### `of`

Type: Story export

Specifies which story is rendered by the `Story` block. If no `of` is defined and the MDX file is [attached](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md#attached-vs-unattached), the primary (first) story will be rendered.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-story
---

# Subtitle

The `Subtitle` block can serve as a secondary heading for your docs entry.

![Screenshot of Subtitle block](../../_assets/api/doc-block-title-subtitle-description.png)

```mdx title="ButtonDocs.mdx"

This is the subtitle
```

## Subtitle

```js

```

`Subtitle` is configured with the following props:

### `children`

Type: `JSX.Element | string`

Default: `parameters.docs.subtitle`

Provides the content.

### `of`

Type: CSF file exports

Specifies which meta's subtitle is displayed.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-subtitle
---

# TableOfContents

The `TableOfContents` block renders a table of contents for the current documentation page, allowing users to navigate between sections quickly. It appears as a fixed sidebar on the right side of the documentation page and is hidden on smaller screens (below 768px).

The table of contents is enabled and configured via the `docs.toc` [parameter](https://storybook.js.org/docs/writing-stories/parameters.md) rather than being added directly to MDX files. When enabled, it is automatically rendered alongside the page content by [Storybook's docs container](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md).

For a step-by-step guide on enabling and customizing the table of contents, see the [Generate a table of contents](https://storybook.js.org/docs/writing-docs/autodocs.md#generate-a-table-of-contents) section in the Autodocs documentation.

## Enabling the table of contents

Enable the table of contents globally in your Storybook preview configuration:

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      toc: true, // 👈 Enables the table of contents
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      toc: true, // 👈 Enables the table of contents
    },
  },
});
```

You can also enable or disable it for specific components in their stories file:

```ts
// MyComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const meta = {
  component: MyComponent,
  tags: ['autodocs'],
  parameters: {
    docs: {
      toc: {
        disable: true, // 👈 Disables the table of contents
      },
    },
  },
} satisfies Meta<typeof MyComponent>;

export default meta;
```

```ts
// MyComponent.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: MyComponent,
  tags: ['autodocs'],
  parameters: {
    docs: {
      toc: {
        disable: true, // 👈 Disables the table of contents
      },
    },
  },
});
```

## `toc` parameter options

The `docs.toc` parameter accepts either `true` (to enable with defaults) or an object with the following properties:

### `contentsSelector`

Type: `string`

Default: `'.sbdocs-content'`

CSS selector for the container to search for headings. Use this if you have a custom docs page layout.

### `disable`

Type: `boolean`

Default: `false`

When `true`, it hides the table of contents for the documentation page. A hidden (empty) container is still rendered to preserve the page layout.

### `headingSelector`

Type: `string`

Default: `'h3'`

CSS selector that defines which heading levels to include in the table of contents. For example, use `'h1, h2, h3'` to include the top three heading levels.

### `ignoreSelector`

Type: `string`

Default: `'.docs-story *, .skip-toc'`

CSS selector for headings to exclude from the table of contents. By default, headings inside story blocks are excluded. To also exclude a specific heading, add the `skip-toc` class to it.

### `title`

Type: `string | null | ReactElement`

Default: `'Table of contents'` (visually hidden)

Text or element to display as the title above the table of contents. Set to `null` to render no title. When a string is provided, it is rendered as a visually hidden `<h2>` by default; pass a non-empty string to make it visible.

### `unsafeTocbotOptions`

Type: `object`

Provides additional configuration options passed directly to the underlying [`Tocbot`](https://tscanlin.github.io/tocbot/) library. These options are not guaranteed to remain available in future versions of Storybook.

```ts
// .storybook/preview.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const preview: Preview = {
  parameters: {
    docs: {
      toc: {
        contentsSelector: '.sbdocs-content',
        headingSelector: 'h1, h2, h3',
        ignoreSelector: '#primary',
        title: 'Table of Contents',
        disable: false,
        unsafeTocbotOptions: {
          orderedList: false,
        },
      },
    },
  },
};

export default preview;
```

```ts
// .storybook/preview.tsx — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

export default definePreview({
  addons: [addonDocs()],
  parameters: {
    docs: {
      toc: {
        contentsSelector: '.sbdocs-content',
        headingSelector: 'h1, h2, h3',
        ignoreSelector: '#primary',
        title: 'Table of Contents',
        disable: false,
        unsafeTocbotOptions: {
          orderedList: false,
        },
      },
    },
  },
});
```
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-tableofcontents
---

# Title

The `Title` block serves as the primary heading for your docs entry. It is typically used to provide the component or page name.

![Screenshot of Title block](../../_assets/api/doc-block-title-subtitle-description.png)

```mdx title="ButtonDocs.mdx"

This is the title
```

## Title

```js

```

`Title` is configured with the following props:

### `children`

Type: `JSX.Element | string`

Provides the content. Falls back to value of `title` in an [attached](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md#attached-vs-unattached) CSF file (or value derived from [autotitle](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md#csf-30-auto-titles)), trimmed to the last segment. For example, if the title value is `'path/to/components/Button'`, the default content is `'Button'`.

### `of`

Type: CSF file exports

Specifies which meta's title is displayed.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-title
---

# Typeset

The `Typeset` block helps document the fonts used throughout your project.

![Screenshot of Typeset block](../../_assets/api/doc-block-typeset.png)

```mdx title="Typography.mdx"

export const typography = {
  type: {
    primary: '"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif',
  },
  weight: {
    regular: '400',
    bold: '700',
    extrabold: '800',
    black: '900',
  },
  size: {
    s1: 12,
    s2: 14,
    s3: 16,
    m1: 20,
    m2: 24,
    m3: 28,
    l1: 32,
    l2: 40,
    l3: 48,
  },
};

export const SampleText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';

# Typography

**Font:** Nunito Sans

**Weights:** 400(regular), 700(bold), 800(extrabold), 900(black)

```

## Typeset

```js

```

`Typeset` is configured with the following props:

### `fontFamily`

Type: `string`

Provides a font family to be displayed.

### `fontSizes`

Type: `(string | number)[]`

Provides a list of available font sizes (in `px`).

### `fontWeight`

Type: `number`

Specifies the weight of the font to be displayed.

### `sampleText`

Type: `string`

Sets the text to be displayed.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-typeset
---

# Unstyled

The `Unstyled` block is a special block that disables Storybook's default styling in MDX docs wherever it is added.

By default, most elements (like `h1`, `p`, etc.) in docs have a few default styles applied to ensure the docs look good. However, sometimes you might want some of your content to not have these styles applied. In those cases, wrap the content with the `Unstyled` block to remove the default styles.

```mdx title="ButtonDocs.mdx"

> This block quote will be styled

... and so will this paragraph.

  > This block quote will not be styled

... neither will this paragraph, nor the following component (which contains an \<h1\>):

```

Yields:

![Screenshot of Unstyled Doc Block](../../_assets/api/doc-block-unstyled.png)

The other blocks like [`Story`](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md) and [`Canvas`](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) are already unstyled, so there’s no need to wrap those in the `Unstyled` block to ensure that Storybook’s styles don’t bleed into the stories. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block.

Due to how CSS inheritance works it’s best to always add the Unstyled block to the root of your MDX, and not nested into other elements. The following example will cause some Storybook styles like `color` to be inherited into `CustomComponent` because they are applied to the root `div`:

```md
<div>
  
    
  
</div>
```

## Unstyled

```js

```

`Unstyled` is configured with the following props:

### `children`

Type: `React.ReactNode`

Provides the content to which you do _not_ want to apply default docs styles.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-unstyled
---

# useOf

The default blocks supplied by Storybook do not fit all use cases, so you might want to write your own blocks.

If your own doc blocks need to interface with annotations from Storybook—that is stories, meta or components—you can use the `useOf` hook. Pass in a module export of a story, meta, or component and it will return its annotated form (with applied parameters, args, loaders, decorators, play function) that you can then use for anything you like. In fact, most of the existing blocks like [`Description`](https://storybook.js.org/docs/api/doc-blocks/doc-block-description.md) and [`Canvas`](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) use `useOf` under the hood.

Here’s an example of how the`useOf` hook could be used to create a custom block that displays the name of the story:

```jsx title=".storybook/blocks/StoryName.jsx"

/**
 * A block that displays the story name or title from the of prop
 * - if a story reference is passed, it renders the story name
 * - if a meta reference is passed, it renders the stories' title
 * - if nothing is passed, it defaults to the primary story
 */
export const StoryName = ({ of }) => {
  const resolvedOf = useOf(of || 'story', ['story', 'meta']);
  switch (resolvedOf.type) {
    case 'story': {
      return <h1>{resolvedOf.story.name}</h1>;
    }
    case 'meta': {
      return <h1>{resolvedOf.preparedMeta.title}</h1>;
    }
  }
  return null;
};
```

```mdx title="ButtonDocs.mdx"

```

## useOf

### Type

```ts
(
  moduleExportOrType: ModuleExport | 'story' | 'meta' | 'component',
  validTypes?: Array<'story' | 'meta' | 'component'>,
) => EnhancedResolvedModuleExportType;
```

### Parameters

#### `moduleExportOrType`

(**Required**)

Type: `ModuleExport | 'story' | 'meta' | 'component'`

Provides the story export, meta export, component export, or CSF file exports from which you get annotations.

When the custom block is in an [attached doc](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md#attached-vs-unattached), it’s also possible to get the primary (first) story, meta, or component by passing in a string instead. This is useful as a fallback, so the `of` prop can be omitted in your block. The most common pattern is using this as `useOf(props.of || 'story')` which will fall back to the primary story if no `of` prop is defined.

- `useOf('story')` returns the annotated primary story in attached mode; error in unattached mode
- `useOf('meta')` returns the annotated meta in attached mode; error in unattached mode
- `useOf('component')` returns the annotated component specified in the meta in attached mode; error in unattached mode

#### `validTypes`

Type: `Array<'story' | 'meta' | 'component'>`

Optionally specify an array of valid types that your block accepts. Passing anything other than the valid type(s) will result in an error. For example, the [`Canvas`](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md) block uses `useOf(of, ['story'])`, which ensures it only accepts a reference to a story, not a meta or component.

### Return

The return value depends on the matched type:

#### `EnhancedResolvedModuleExportType['type'] === 'story'`

Type: `{ type: 'story', story: PreparedStory }`

For stories, annotated stories are returned as is. They are prepared, meaning that they are already merged with project and meta annotations.

#### `EnhancedResolvedModuleExportType['type'] === 'meta'`

Type: `{ type: 'meta', csfFile: CSFFile, preparedMeta: PreparedMeta }`

For meta, the parsed CSF file is returned, along with prepared annotated meta. That is, project annotations merged with meta annotations, but no story annotations.

#### `EnhancedResolvedModuleExportType['type'] === 'component'`

Type: `{ type: 'component', component: Component, projectAnnotations: NormalizedProjectAnnotations }`

For components, the component is returned along with project annotations; no meta or story annotations.

Note that it’s often impossible for the hook to determine if a component is passed in or any other object, so it behaves like an `unknown` type as well.
> Source: https://storybook.js.org/docs/api/doc-blocks/doc-block-useof
---

# Portable stories in Vitest

Portable stories in Vitest are currently only supported in [React](https://storybook.js.org/docs/api/portable-stories/?renderer=react.md), [Vue](https://storybook.js.org/docs/api/portable-stories/?renderer=vue.md) and [Svelte](https://storybook.js.org/docs/api/portable-stories/?renderer=svelte.md) projects.

Storybook now recommends testing your stories in Vitest with the [Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon.md), which automatically transforms stories into real Vitest tests (using this API under the hood).

This API is still available for those who prefer to use portable stories directly, but we recommend using the Vitest addon for a more streamlined testing experience.

Portable stories are Storybook [stories](https://storybook.js.org/docs/writing-stories.md) which can be used in external environments, such as [Vitest](https://vitest.dev).

Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Vitest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable.

**Using `Next.js`?** You can test your Next.js stories with Vitest by installing and setting up the `@storybook/nextjs-vite` which re-exports [vite-plugin-storybook-nextjs](https://github.com/storybookjs/vite-plugin-storybook-nextjs) package.

## composeStories

`composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories.

By default, the composed story will render the component with the [args](https://storybook.js.org/docs/writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args.

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// Import all stories and the component annotations from the stories file

// Every component that is returned maps 1:1 with the stories,
// but they already contain all annotations from story, meta, and project levels
const { Primary, Secondary } = composeStories(stories);

test('renders primary button with default args', async () => {
  await Primary.run();
  const buttonElement = screen.getByText('Text coming from args in stories file!');
  expect(buttonElement).not.toBeNull();
});

test('renders primary button with overridden props', async () => {
  // You can override props by passing them in the context argument of the run function
  await Primary.run({ args: { ...Primary.args, children: 'Hello world' } });
  const buttonElement = screen.getByText(/Hello world/i);
  expect(buttonElement).not.toBeNull();
});
```

### Type

```ts
(
  csfExports: CSF file exports,
  projectAnnotations?: ProjectAnnotations
) => Record<string, ComposedStoryFn>
```

### Parameters

#### `csfExports`

(**Required**)

Type: CSF file exports

Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'`

#### `projectAnnotations`

Type: `ProjectAnnotation | ProjectAnnotation[]`

Specifies the project annotations to be applied to the composed stories.

This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.

This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.

### Return

Type: `Record<string, ComposedStoryFn>`

An object where the keys are the names of the stories and the values are the composed stories.

Additionally, the composed story will have the following properties:

| Property   | Type                                      | Description                                                      |
| ---------- | ----------------------------------------- | ---------------------------------------------------------------- |
| args       | `Record<string, any>`                     | The story's [args](https://storybook.js.org/docs/writing-stories/args.md)               |
| argTypes   | `ArgType`                                 | The story's [argTypes](https://storybook.js.org/docs/api/arg-types.md)                         |
| id         | `string`                                  | The story's id                                                   |
| parameters | `Record<string, any>`                     | The story's [parameters](https://storybook.js.org/docs/api/parameters.md)                      |
| play       | `(context) => Promise<void> \| undefined` | Executes the play function of a given story                      |
| run        | `(context) => Promise<void> \| undefined` | [Mounts and executes the play function](#3-run) of a given story |
| storyName  | `string`                                  | The story's name                                                 |
| tags       | `string[]`                                | The story's [tags](https://storybook.js.org/docs/writing-stories/tags.md)               |

## composeStory

You can use `composeStory` if you wish to compose a single story for a component.

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// Returns a story which already contains all annotations from story, meta and global levels
const Primary = composeStory(PrimaryStory, meta);

test('renders primary button with default args', async () => {
  await Primary.run();

  const buttonElement = screen.getByText('Text coming from args in stories file!');
  expect(buttonElement).not.toBeNull();
});

test('renders primary button with overridden props', async () => {
  await Primary.run({ args: { ...Primary.args, label: 'Hello world' } });

  const buttonElement = screen.getByText(/Hello world/i);
  expect(buttonElement).not.toBeNull();
});
```

### Type

```ts
(
  story: Story export,
  componentAnnotations: Meta,
  projectAnnotations?: ProjectAnnotations,
  exportsName?: string
) => ComposedStoryFn
```

### Parameters

#### `story`

(**Required**)

Type: `Story export`

Specifies which story you want to compose.

#### `componentAnnotations`

(**Required**)

Type: `Meta`

The default export from the stories file containing the [`story`](#story).

#### `projectAnnotations`

Type: `ProjectAnnotation | ProjectAnnotation[]`

Specifies the project annotations to be applied to the composed story.

This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.

This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.

#### `exportsName`

Type: `string`

You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here.

### Return

Type: `ComposedStoryFn`

A single [composed story](#return).

## setProjectAnnotations

This API should be called once, before the tests run, typically in a [setup file](https://vitest.dev/config/#setupfiles). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well.

These are the configurations needed in the setup file:

- preview annotations: those defined in `.storybook/preview.tsx`
- addon annotations (optional): those exported by addons
- beforeAll: code that runs before all tests ([more info](https://storybook.js.org/docs/writing-tests/interaction-testing.md#beforeall))

```tsx
// setupTest.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// 👇 Import the exported annotations, if any, from the addons you're using; otherwise remove this

const annotations = setProjectAnnotations([previewAnnotations, addonAnnotations]);

// Run Storybook's beforeAll hook
beforeAll(annotations.beforeAll);
```

Sometimes a story can require an addon's [decorator](https://storybook.js.org/docs/writing-stories/decorators.md) or [loader](https://storybook.js.org/docs/writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above.

Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.*` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above.

If you need to configure Testing Library's `render` or use a different render function, please let us know in [this discussion](https://github.com/storybookjs/storybook/discussions/28532) so we can learn more about your needs.

### Type

```ts
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => ProjectAnnotation;
```

### Parameters

#### `projectAnnotations`

(**Required**)

Type: `ProjectAnnotation | ProjectAnnotation[]`

A set of project [annotations](#annotations) (those defined in `.storybook/preview.*`) or an array of sets of project annotations, which will be applied to all composed stories.

## Annotations

Annotations are the metadata applied to a story, like [args](https://storybook.js.org/docs/writing-stories/args.md), [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [loaders](https://storybook.js.org/docs/writing-stories/loaders.md), and [play functions](https://storybook.js.org/docs/writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project.

## Story pipeline

To preview your stories in Storybook, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline:

![A flow diagram of the story pipeline. First, set project annotations. Collect annotations (decorators, args, etc) which are exported by addons and the preview file. Second, compose story. Create renderable elements based on the stories passed onto the API. Third, run. Mount the component and execute all the story lifecycle hooks, including the play function.](../../_assets/api/story-pipeline.png)

When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment:

### 1. Apply project-level annotations

[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotations are those defined in your `.storybook/preview.*` file and by addons you're using. In portable stories, these annotations are not applied automatically — you must apply them yourself.

👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.

### 2. Compose

The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). The outcome is a renderable component that represents the render function of the story.

### 3. Run

Finally, stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](https://storybook.js.org/docs/writing-stories/loaders.md), [beforeEach](https://storybook.js.org/docs/writing-tests/interaction-testing.md#run-code-before-each-story-in-a-file) or by having all the story code in the play function when using the [mount](https://storybook.js.org/docs/writing-tests/interaction-testing.md#run-code-before-the-component-gets-rendered). In portable stories, all of these steps will be executed when you call the `run` method of the composed story.

👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `run` method to be called.

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { Primary } = composeStories(stories);

test('renders and executes the play function', async () => {
  // Mount story and run interactions
  await Primary.run();
});
```

If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.

## Overriding globals

If your stories behave differently based on [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story:

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

test('renders in English', async () => {
  const Primary = composeStory(
    PrimaryStory,
    meta,
    { globals: { locale: 'en' } }, // 👈 Project annotations to override the locale
  );

  await Primary.run();
});

test('renders in Spanish', async () => {
  const Primary = composeStory(PrimaryStory, meta, { globals: { locale: 'es' } });

  await Primary.run();
});
```
> Source: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest
---

# Portable stories in Jest

Portable stories in Jest are currently only supported in [React](https://storybook.js.org/docs/api/portable-stories/?renderer=react.md) and [Vue](https://storybook.js.org/docs/api/portable-stories/?renderer=vue.md) projects.

If you are using the [experimental CSF Factories format](https://storybook.js.org/docs/api/csf/csf-next.md), you don't need to use the portable stories API. Instead, you can [import and use your stories directly](https://storybook.js.org/docs/api/csf/csf-next.md#manual).

Portable stories are Storybook [stories](https://storybook.js.org/docs/writing-stories.md) which can be used in external environments, such as [Jest](https://jestjs.io).

Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Jest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable.

The API specified here is available in Storybook `8.2.7` and up. If you're using an older version of Storybook, you can upgrade to the latest version (`npx storybook@latest upgrade`) to use this API. If you're unable to upgrade, you can use previous API, which uses the `.play()` method instead of `.run()`, but is otherwise identical.

**Using `Next.js`?** You need to do three things differently when using portable stories in Jest with Next.js projects:

- Configure the [`next/jest.js` transformer](https://nextjs.org/docs/pages/building-your-application/testing/jest#manual-setup), which will handle all of the necessary Next.js configuration for you.
- Import [`composeStories`](#composestories) or [`composeStory`](#composestory) from the `@storybook/nextjs` package (e.g. `import { composeStories } from '@storybook/nextjs'`).
- Set up [internal module aliases](https://storybook.js.org/docs/get-started/frameworks/nextjs.md#storybooknextjsexport-mocks) to ensure the framework configuration works correctly and to be able to mock and assert on them.

## composeStories

`composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories.

By default, the composed story will render the component with the [args](https://storybook.js.org/docs/writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args.

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// Import all stories and the component annotations from the stories file

// Every component that is returned maps 1:1 with the stories,
// but they already contain all annotations from story, meta, and project levels
const { Primary, Secondary } = composeStories(stories);

test('renders primary button with default args', () => {
  render();
  const buttonElement = screen.getByText('Text coming from args in stories file!');
  expect(buttonElement).not.toBeNull();
});

test('renders primary button with overridden props', () => {
  // You can override props and they will get merged with values from the story's args
  render(Hello world);
  const buttonElement = screen.getByText(/Hello world/i);
  expect(buttonElement).not.toBeNull();
});
```

### Type

```ts
(
  csfExports: CSF file exports,
  projectAnnotations?: ProjectAnnotations
) => Record<string, ComposedStoryFn>
```

### Parameters

#### `csfExports`

(**Required**)

Type: CSF file exports

Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'`

#### `projectAnnotations`

Type: `ProjectAnnotation | ProjectAnnotation[]`

Specifies the project annotations to be applied to the composed stories.

This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.

This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.

### Return

Type: `Record<string, ComposedStoryFn>`

An object where the keys are the names of the stories and the values are the composed stories.

Additionally, the composed story will have the following properties:

| Property   | Type                                      | Description                                                      |
| ---------- | ----------------------------------------- | ---------------------------------------------------------------- |
| args       | `Record<string, any>`                     | The story's [args](https://storybook.js.org/docs/writing-stories/args.md)               |
| argTypes   | `ArgType`                                 | The story's [argTypes](https://storybook.js.org/docs/api/arg-types.md)                         |
| id         | `string`                                  | The story's id                                                   |
| parameters | `Record<string, any>`                     | The story's [parameters](https://storybook.js.org/docs/api/parameters.md)                      |
| play       | `(context) => Promise<void> \| undefined` | Executes the play function of a given story                      |
| run        | `(context) => Promise<void> \| undefined` | [Mounts and executes the play function](#3-run) of a given story |
| storyName  | `string`                                  | The story's name                                                 |
| tags       | `string[]`                                | The story's [tags](https://storybook.js.org/docs/writing-stories/tags.md)               |

## composeStory

You can use `composeStory` if you wish to compose a single story for a component.

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

test('onclick handler is called', () => {
  // Returns a story which already contains all annotations from story, meta and global levels
  const Primary = composeStory(PrimaryStory, meta);

  const onClickSpy = jest.fn();
  await Primary.run({ args: { ...Primary.args, onClick: onClickSpy } });

  const buttonElement = screen.getByRole('button');
  buttonElement.click();
  expect(onClickSpy).toHaveBeenCalled();
});
```

### Type

```ts
(
  story: Story export,
  componentAnnotations: Meta,
  projectAnnotations?: ProjectAnnotations,
  exportsName?: string
) => ComposedStoryFn
```

### Parameters

#### `story`

(**Required**)

Type: `Story export`

Specifies which story you want to compose.

#### `componentAnnotations`

(**Required**)

Type: `Meta`

The default export from the stories file containing the [`story`](#story).

#### `projectAnnotations`

Type: `ProjectAnnotation | ProjectAnnotation[]`

Specifies the project annotations to be applied to the composed story.

This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.

This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.

#### `exportsName`

Type: `string`

You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here.

### Return

Type: `ComposedStoryFn`

A single [composed story](#return).

## setProjectAnnotations

This API should be called once, before the tests run, typically in a [setup file](https://jestjs.io/docs/configuration#setupfiles-array). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well.

These are the configurations needed in the setup file:

- preview annotations: those defined in `.storybook/preview.tsx`
- addon annotations (optional): those exported by addons
- beforeAll: code that runs before all tests ([more info](https://storybook.js.org/docs/writing-tests/interaction-testing.md#beforeall))

```tsx
// setupTest.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// 👇 Import the exported annotations, if any, from the addons you're using; otherwise remove this

const annotations = setProjectAnnotations([previewAnnotations, addonAnnotations]);

// Supports beforeAll hook from Storybook
beforeAll(annotations.beforeAll);
```

Sometimes a story can require an addon's [decorator](https://storybook.js.org/docs/writing-stories/decorators.md) or [loader](https://storybook.js.org/docs/writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above.

Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.*` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above.

If you need to configure Testing Library's `render` or use a different render function, please let us know in [this discussion](https://github.com/storybookjs/storybook/discussions/28532) so we can learn more about your needs.

### Type

```ts
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => ProjectAnnotation;
```

### Parameters

#### `projectAnnotations`

(**Required**)

Type: `ProjectAnnotation | ProjectAnnotation[]`

A set of project [annotations](#annotations) (those defined in `.storybook/preview.*`) or an array of sets of project annotations, which will be applied to all composed stories.

## Annotations

Annotations are the metadata applied to a story, like [args](https://storybook.js.org/docs/writing-stories/args.md), [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [loaders](https://storybook.js.org/docs/writing-stories/loaders.md), and [play functions](https://storybook.js.org/docs/writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project.

## Story pipeline

To preview your stories in Storybook, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline:

![A flow diagram of the story pipeline. First, set project annotations. Collect annotations (decorators, args, etc) which are exported by addons and the preview file. Second, compose story. Create renderable elements based on the stories passed onto the API. Third, run. Mount the component and execute all the story lifecycle hooks, including the play function.](../../_assets/api/story-pipeline.png)

When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment:

### 1. Apply project-level annotations

[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotations are those defined in your `.storybook/preview.*` file and by addons you're using. In portable stories, these annotations are not applied automatically — you must apply them yourself.

👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.

### 2. Compose

The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). The outcome is a renderable component that represents the render function of the story.

### 3. Run

Finally, stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](https://storybook.js.org/docs/writing-stories/loaders.md), [beforeEach](https://storybook.js.org/docs/writing-tests/interaction-testing.md#run-code-before-each-story-in-a-file) or by having all the story code in the play function when using the [mount](https://storybook.js.org/docs/writing-tests/interaction-testing.md#run-code-before-the-component-gets-rendered). In portable stories, all of these steps will be executed when you call the `run` method of the composed story.

👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `run` method to be called.

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

const { Primary } = composeStories(stories);

test('renders and executes the play function', async () => {
  // Mount story and run interactions
  await Primary.run();
});
```

If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.

## Overriding globals

If your stories behave differently based on [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story:

```tsx
// Button.test.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

test('renders in English', async () => {
  const Primary = composeStory(
    PrimaryStory,
    meta,
    { globals: { locale: 'en' } }, // 👈 Project annotations to override the locale
  );

  await Primary.run();
});

test('renders in Spanish', async () => {
  const Primary = composeStory(PrimaryStory, meta, { globals: { locale: 'es' } });

  await Primary.run();
});
```
> Source: https://storybook.js.org/docs/api/portable-stories/portable-stories-jest
---

# Portable stories in Playwright CT

(⚠️ **Experimental**)

Portable stories are currently only supported in [React](https://storybook.js.org/docs/api/portable-stories/?renderer=react.md) and [Vue](https://storybook.js.org/docs/api/portable-stories/?renderer=vue.md) projects.

The portable stories API for Playwright CT is experimental. Playwright CT itself is also experimental. Breaking changes might occur in either library in upcoming releases.

Portable stories are Storybook [stories](https://storybook.js.org/docs/writing-stories.md) which can be used in external environments, such as [Playwright Component Tests (CT)](https://playwright.dev/docs/test-components).

Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Playwright CT, you can use the [`createTest`](#createtest) function, which extends Playwright's test functionality to add a custom `mount` mechanism, to take care of the story pipeline for you.

Your project must be using React 18+ to use the portable stories API with Playwright CT.

**Using `Next.js`?** The portable stories API is not yet supported in Next.js with Playwright CT.

## createTest

(⚠️ **Experimental**)

Instead of using Playwright's own `test` function, you can use Storybook's special `createTest` function to [extend Playwright's base fixture](https://playwright.dev/docs/test-fixtures#creating-a-fixture) and override the `mount` function to load, render, and play the story. This function is experimental and is subject to changes.

```tsx
// Button.playwright.test.tsx

// See explanation below for `.portable` stories file

const test = createTest(base);

test('renders primary button', async ({ mount }) => {
  // The mount function will execute all the necessary steps in the story,
  // such as loaders, render, and play function
  await mount(<stories.Primary />);
});

test('renders primary button with overridden props', async ({ mount }) => {
  // You can pass custom props to your component via JSX
  const component = await mount(<stories.Primary label="label from test" />);
  await expect(component).toContainText('label from test');
  await expect(component.getByRole('button')).toHaveClass(/storybook-button--primary/);
});
```

The code which you write in your Playwright test file is transformed and orchestrated by Playwright, where part of the code executes in Node, while other parts execute in the browser.

Because of this, you have to compose the stories _in a separate file than your own test file_:

```ts title="Button.stories.portable.ts"
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

// This function will be executed in the browser
// and compose all stories, exporting them in a single object
export default composeStories(stories);
```

You can then import the composed stories in your Playwright test file, as in the example above.

### Type

```ts
createTest(
  baseTest: PlaywrightFixture
) => PlaywrightFixture
```

### Parameters

#### `baseTest`

(**Required**)

Type: `PlaywrightFixture`

The base test function to use, e.g. `test` from Playwright.

### Return

Type: `PlaywrightFixture`

A Storybook-specific test function with the custom `mount` mechanism.

## setProjectAnnotations

This API should be called once, before the tests run, in [`playwright/index.ts`](https://playwright.dev/docs/test-components#step-1-install-playwright-test-for-components-for-your-respective-framework). This will make sure that when `mount` is called, the project annotations are taken into account as well.

These are the configurations needed in the setup file:

- preview annotations: those defined in `.storybook/preview.tsx`
- addon annotations (optional): those exported by addons
- beforeAll: code that runs before all tests ([more info](https://storybook.js.org/docs/writing-tests/interaction-testing.md#beforeall))

```tsx
// playwright/index.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

// 👇 Import the exported annotations, if any, from the addons you're using; otherwise remove this

const annotations = setProjectAnnotations([previewAnnotations, addonAnnotations]);

// Supports beforeAll hook from Storybook
test.beforeAll(annotations.beforeAll);
```

Sometimes a story can require an addon's [decorator](https://storybook.js.org/docs/writing-stories/decorators.md) or [loader](https://storybook.js.org/docs/writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above.

Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.*` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above.

### Type

```ts
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => ProjectAnnotation;
```

### Parameters

#### `projectAnnotations`

(**Required**)

Type: `ProjectAnnotation | ProjectAnnotation[]`

A set of project [annotations](#annotations) (those defined in `.storybook/preview.*`) or an array of sets of project annotations, which will be applied to all composed stories.

## Annotations

Annotations are the metadata applied to a story, like [args](https://storybook.js.org/docs/writing-stories/args.md), [decorators](https://storybook.js.org/docs/writing-stories/decorators.md), [loaders](https://storybook.js.org/docs/writing-stories/loaders.md), and [play functions](https://storybook.js.org/docs/writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project.

[Read more about Playwright's component testing](https://playwright.dev/docs/test-components#test-stories).

## Story pipeline

To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline:

![A flow diagram of the story pipeline. First, set project annotations. Collect annotations (decorators, args, etc) which are exported by addons and the preview file. Second, compose story. Create renderable elements based on the stories passed onto the API. Third, render story. Load, mount, and execute the play function as part of the portable stories API.](../../_assets/api/story-pipeline-playwright.png)

When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment:

### 1. Apply project-level annotations

[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotations are those defined in your `.storybook/preview.*` file and by addons you're using. In portable stories, these annotations are not applied automatically — you must apply them yourself.

👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.

### 2. Prepare, load, render, and play

The story pipeline includes preparing the story, [loading data](https://storybook.js.org/docs/writing-stories/loaders.md), rendering the story, and [playing interactions](https://storybook.js.org/docs/writing-tests/interaction-testing.md#debugging-interaction-tests). In portable stories within Playwright CT, the `mount` function takes care of these steps for you.

👉 For this, you use the [`createTest`](#createtest) API.

If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.

## Overriding globals

If your stories behave differently based on [globals](https://storybook.js.org/docs/essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story:

```ts
// Button.stories.portable.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

export const PrimaryEnglish = composeStory(
  Primary,
  meta,
  { globals: { locale: 'en' } }, // 👈 Project annotations to override the locale
);

export const PrimarySpanish = composeStory(Primary, meta, { globals: { locale: 'es' } });
```

```ts
// Button.stories.portable.ts — CSF Next 🧪

export const PrimaryEnglish = Primary.extend({
  globals: { locale: 'en' }, // 👈 Project annotations to override the locale
});

export const PrimarySpanish = Primary.extend({
  globals: { locale: 'es' },
});
```

You can then use those composed stories in your Playwright test file using the [`createTest`](#createtest) function.
> Source: https://storybook.js.org/docs/api/portable-stories/portable-stories-playwright
---

# Frameworks

Storybook is architected to support diverse web frameworks, including React, Vue, Angular, Web Components, Svelte, and over a dozen others. This guide helps you get started on adding new framework support for Storybook.

## Scaffolding a new framework

The first thing to do is to scaffold your framework support in its own repo.

We recommend adopting the same project structure as the Storybook monorepo. That structure contains the framework package (`app/<framework>`) and an example app (`examples/<framework>-kitchen-sink`) as well as other associated documentation and configuration as needed.

It may seem like a little more hierarchy than what’s necessary. But because the structure mirrors the way Storybook’s monorepo is structured, you can reuse Storybook’s tooling. It also makes it easier to move the framework into the Storybook monorepo later if that is desirable.

We recommend using `@storybook/html` as a starter framework since it’s the simplest and contains no framework-specific peculiarities. There is a boilerplate to get you started [here](https://github.com/CodeByAlex/storybook-framework-boilerplate).

## Framework architecture

Supporting a new framework in Storybook typically consists of two main aspects:

1. Configuring the server. In Storybook, the server is the node process that runs when you run `storybook dev` or `storybook build`. Configuring the server typically means configuring babel and webpack in framework-specific ways.

2. Configuring the client. The client is the code that runs in the browser, and configuring it, means providing a framework-specific story rendering function.

## Configuring the server

Storybook has the concept of [presets](https://storybook.js.org/docs/addons/writing-presets.md), which are typically babel/webpack configurations for file loading. If your framework has its own file format (e.g., “.vue”), you might need to transform them into JavaScript files at load time. If you assume every user of your framework needs this, you should add it to the framework. So far, every framework added to Storybook has done it because Storybook’s core configuration is extremely minimal.

### Package structure

It's helpful to understand Storybook's package structure before adding a framework preset. Each framework typically exposes two executables in its `package.json`:

```json title="package.json"
{
  "bin": {
    "storybook": "./bin/index.js",
    "build-storybook": "./bin/build.js"
  }
}
```

These scripts pass an `options` object to `storybook/internal/server`, a library that abstracts all of Storybook’s framework-independent code.

For example, here’s the boilerplate to start the dev server with `storybook dev`:

```ts
// your-framework/src/server/index.ts

buildDev(options);
```

Thus the essence of adding framework presets is just filling in that options object.

### Server options

As described above, the server `options` object does the heavy lifting of configuring the server.

Let’s look at the `@storybook/vue`’s options definition:

```ts
// vue/src/server/options.ts

export default {
  packageJson: JSON.parse(readFileSync(pkg.up({ cwd: process.cwd() }))),
  framework: 'vue',
  frameworkPresets: [import.meta.resolve('./framework-preset-vue.js')],
};
```

The value of the `framework` option (i.e., ‘vue’) is something that gets passed to addons and allows them to do specific tasks related to your framework.

The essence of this file is the framework presets, and these are standard [Storybook presets](https://storybook.js.org/docs/addons/writing-presets.md) -- you can look at framework packages in the Storybook monorepo (e.g. [React](https://github.com/storybookjs/storybook/blob/next/code/frameworks/react-vite/src/preset.ts), [Vue](https://github.com/storybookjs/storybook/blob/next/code/frameworks/vue3-vite/src/preset.ts), [Web Components](https://github.com/storybookjs/storybook/blob/next/code/frameworks/web-components-vite/src/preset.ts)) to see examples of framework-specific customizations.

While developing your custom framework, not maintained by Storybook, you can specify the path to the location file with the `frameworkPath` key:

```ts
// my-framework/src/server/options.ts

export default {
  packageJson: JSON.parse(readFileSync(pkg.up({ cwd: process.cwd() }))),
  framework: 'my-framework',
  frameworkPath: '@my-framework/storybook',
  frameworkPresets: [import.meta.resolve('./framework-preset-my-framework.js')],
};
```

You can add a relative path to `frameworkPath`. Don't forget that they resolve from the Storybook configuration directory (i.e., `.storybook`) by default.

Make sure the `frameworkPath` ends up at the `dist/client/index.js` file within your framework app.

## Configuring the client

To configure the client, you must provide a framework-specific render function. Before diving into the details, it’s essential to understand how user-written stories relate to what renders on the screen.

### Renderable objects

Storybook stories are ES6 objects that return a “renderable object.”

Consider the following React story:

```js
// Button.stories.js|jsx

export default {
  component: Button,
};

export const Sample = {
  render: () => ,
};
```

In this case, the renderable object is the React element, ``.

In most other frameworks, the renderable object is actually a plain JavaScript object.

Consider the following hypothetical example:

```ts
// Button.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

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

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

export const Sample: Story = {
  render: () => ({
    template: '<button :label=label />',
    data: {
      label: 'hello button',
    },
  }),
};
```

```ts
// Button.stories.ts|tsx — CSF Next 🧪

const meta = preview.meta({
  component: Button,
});

export const Sample = meta.story({
  render: () => ({
    template: '<button :label=label />',
    data: {
      label: 'hello button',
    },
  }),
});
```

The design of this “renderable object” is framework-specific and should ideally match the idioms of that framework.

### Render function

The framework's render function is the entity responsible for converting the renderable object into DOM nodes. It is typically of the form:

```js
// your-framework/src/client/preview/render.ts
const rootElement = document.getElementById('root');

export default function renderMain({ storyFn }: RenderMainArgs) {
  const storyObj = storyFn();
  const html = fn(storyObj);
  rootElement.innerHTML = html;
}
```

### Package structure

On the client side, the key file is [`src/client/preview.js`](https://storybook.js.org/docs/configure/index.md#configure-story-rendering):

```ts
// your-framework/src/client/preview/index.ts

const api = start(render);

// the boilerplate code
```

The globals file typically sets up a single global variable that client-side code (such as addon-provided decorators) can refer to if needed to understand which framework it's running in:

```ts
// vue/src/client/preview/globals.ts

const { window: globalWindow } = global;

globalWindow.STORYBOOK_ENV = 'vue';
```

The `start` function abstracts all of Storybook’s framework-independent client-side (browser) code, and it takes the render function we defined above. For examples of render functions, see [React](https://github.com/storybookjs/storybook/blob/next/code/renderers/react/src/render.tsx), [Vue](https://github.com/storybookjs/storybook/blob/next/code/renderers/vue3/src/render.ts), [Angular](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/client/render.ts), and [Web Components](https://github.com/storybookjs/storybook/blob/next/code/renderers/web-components/src/render.ts) in the Storybook monorepo.
> Source: https://storybook.js.org/docs/api/new-frameworks
---

# CLI options

The Storybook command line interface (CLI) is the main tool you use to build and develop Storybook.

Storybook collects completely anonymous data to help us improve user experience. Participation is
optional, and you may [opt-out](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out) if you'd not like to
share any information.

## CLI commands

All of the following documentation is available in the CLI by running `storybook --help`.

Passing options to these commands works slightly differently if you're using npm instead of Yarn.
You must prefix all of your options with `--`. For example, `npm run storybook build -- -o
./path/to/build --quiet`.

### `dev`

Compiles and serves a development build of your Storybook that reflects your source code changes in the browser in real-time. It should be run from the root of your project.

```shell
storybook dev [options]
```

Options include:

| Option                          | Description                                                                                                                                                                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--help`                        | Output usage information.<br />`storybook dev --help`                                                                                                                                                                                               |
| `-V`, `--version`               | Output the version number.<br />`storybook dev -V`                                                                                                                                                                                                  |
| `-p`, `--port [number]`         | Port to run Storybook.<br />`storybook dev -p 9009`                                                                                                                                                                                                 |
| `--exact-port`                  | Attempts to run Storybook on the exact port number specified.<br />If the port is already in use, Storybook will exit with an error message.<br />`storybook dev -p 9009 --exact-port`                                                              |
| `-h`, `--host [string]`         | Host to run Storybook.<br />`storybook dev -h my-host.com`                                                                                                                                                                                          |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook dev -c .storybook`                                                                                                                                                                               |
| `--loglevel [level]`            | Controls level of logging during build.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`<br />`storybook dev --loglevel warn`                                                                                  |
| `--https`                       | Serve Storybook over HTTPS. Note: You must provide your own certificate information.<br />`storybook dev --https`                                                                                                                                   |
| `--ssl-ca`                      | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)<br />`storybook dev --ssl-ca my-certificate`                                                                                             |
| `--ssl-cert`                    | Provide an SSL certificate. (Required with --https)<br />`storybook dev --ssl-cert my-ssl-certificate`                                                                                                                                              |
| `--ssl-key`                     | Provide an SSL key. (Required with --https)<br />`storybook dev --ssl-key my-ssl-key`                                                                                                                                                               |
| `--smoke-test`                  | Exit after successful start.<br />`storybook dev --smoke-test`                                                                                                                                                                                      |
| `--ci`                          | CI mode (skip interactive prompts, don't open browser).<br />`storybook dev --ci`                                                                                                                                                                   |
| `--no-open`                     | Do not open Storybook automatically in the browser.<br />`storybook dev --no-open`                                                                                                                                                                  |
| `--quiet`                       | Suppress verbose build output.<br />`storybook dev --quiet`                                                                                                                                                                                         |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook dev --debug`                                                                                                                                                                      |
| `--debug-webpack`               | Display final webpack configurations for debugging purposes.<br />`storybook dev --debug-webpack`                                                                                                                                                   |
| `--stats-json [dir-name]`       | Write stats JSON to disk.<br />Requires Webpack<br />`storybook dev --stats-json /tmp/stats`                                                                                                                                                        |
| `--no-version-updates`          | Skips Storybook's update check.<br />`storybook dev --no-version-updates`                                                                                                                                                                           |
| `--docs`                        | Starts Storybook in documentation mode. Learn more about it in [here](https://storybook.js.org/docs/writing-docs/build-documentation.md#preview-storybooks-documentation).<br />`storybook dev --docs`                                                                        |
| `--initial-path [path]`         | Configures the URL Storybook should open when it opens the browser for the first time.<br />`storybook dev --initial-path=/docs/getting-started--docs`                                                                                              |
| `--preview-url [path]`          | Overrides the default Storybook preview with a custom built preview URL.<br />`storybook dev --preview-url=http://localhost:1337/external-iframe.html`                                                                                              |
| `--force-build-preview`         | Forcefully builds Storybook's preview iframe.<br />Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date.<br />`storybook dev --force-build-preview`                                           |
| `--disable-telemetry`           | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook dev --disable-telemetry`                                                                                                     |
| `--enable-crash-reports`        | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook dev --enable-crash-reports`                                                       |
| `--preview-only`                | Skips Storybook's manager from building and opens the app in "preview only" mode, which is designed to be used in [unsupported browsers](https://storybook.js.org/docs/sharing/publish-storybook.md#build-storybook-for-older-browsers). <br />`storybook dev --preview-only` |

With the release of Storybook 8, the `-s` CLI flag was removed. We recommend using the [static
directory](https://storybook.js.org/docs/configure/integration/images-and-assets.md#serving-static-files-via-storybook)
instead if you need to serve static files.

### `build`

Compiles your Storybook instance so it can be [deployed](https://storybook.js.org/docs/sharing/publish-storybook.md). It should be run from the root of your project.

```shell
storybook build [options]
```

Options include:

| Option                          | Description                                                                                                                                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                  | Output usage information.<br />`storybook build --help`                                                                                                                                                                                        |
| `-V`, `--version`               | Output the version number.<br />`storybook build -V`                                                                                                                                                                                           |
| `-o`, `--output-dir [dir-name]` | Directory where to store built files.<br />`storybook build -o /my-deployed-storybook`                                                                                                                                                         |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook build -c .storybook`                                                                                                                                                                        |
| `--loglevel [level]`            | Controls level of logging during build.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.<br />`storybook build --loglevel warn`                                                                          |
| `--quiet`                       | Suppress verbose build output.<br />`storybook build --quiet`                                                                                                                                                                                  |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook build --debug`                                                                                                                                                               |
| `--debug-webpack`               | Display final webpack configurations for debugging purposes.<br />`storybook build --debug-webpack`                                                                                                                                            |
| `--stats-json [dir-name]`       | Write stats JSON to disk.<br />Requires Webpack<br />`storybook build --stats-json /tmp/stats`                                                                                                                                                 |
| `--docs`                        | Builds Storybook in documentation mode. Learn more about it in [here](https://storybook.js.org/docs/writing-docs/build-documentation.md#publish-storybooks-documentation).<br />`storybook build --docs`                                                                 |
| `--test`                        | Optimize Storybook's production build for performance and tests by removing unnecessary features with the `test` option. Learn more [here](https://storybook.js.org/docs/api/main-config/main-config-build.md).<br />`storybook build --test`                            |
| `--preview-url [path]`          | Overrides the default Storybook preview with a custom built preview URL.<br />`storybook build --preview-url=http://localhost:1337/external-iframe.html`                                                                                       |
| `--force-build-preview`         | Forcefully builds Storybook's preview iframe.<br />Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date.<br />`storybook build --force-build-preview`                                    |
| `--disable-telemetry`           | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook build --disable-telemetry`                                                                                              |
| `--enable-crash-reports`        | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook build --enable-crash-reports`                                                |
| `--preview-only`                | Skips Storybook's manager from building and produces a "preview only" app, which is designed to be used in [unsupported browsers](https://storybook.js.org/docs/sharing/publish-storybook.md#build-storybook-for-older-browsers). <br />`storybook build --preview-only` |

### `init`

We recommend [`create-storybook`](#create-storybook) for new projects. The `init` command will
remain available for backwards compatibility.

Installs and initializes the specified version (e.g., `@latest`, `@8`, `@next`) of Storybook into your project. If no version is specified, the latest version is installed. Read more in the [installation guide](https://storybook.js.org/docs/get-started/install.md).

```shell
storybook[@version] init [options]
```

For example, `storybook@8.4 init` will install Storybook 8.4 into your project.

Options include:

| Option                   | Description                                                                                                                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`           | Output usage information.<br />`storybook init --help`                                                                                                                                         |
| `-b`, `--builder`        | Defines the [builder](https://storybook.js.org/docs/builders.md) to use for your Storybook instance.<br />`storybook init --builder webpack5`                                                                      |
| `-f`, `--force`          | Forcefully installs Storybook into your project, prompting you to overwrite existing files.<br />`storybook init --force`                                                                      |
| `-s`, `--skip-install`   | Skips the dependency installation step. Used only when you need to configure Storybook manually.<br />`storybook init --skip-install`                                                          |
| `-t`, `--type`           | Defines the [framework](https://storybook.js.org/docs/configure/integration/frameworks.md) to use for your Storybook instance.<br />`storybook init --type solid`                                                        |
| `-y`, `--yes`            | Skips interactive prompts and automatically installs Storybook per specified version, including all features.<br />`storybook init --yes`                                                      |
| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated.<br />`storybook init --features docs test a11y`                     |
| `--package-manager`      | Sets the package manager to use when installing Storybook.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook init --package-manager pnpm`                     |
| `--use-pnp`              | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager.<br />`storybook init --use-pnp`               |
| `-p`, `--parser`         | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).<br />Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.<br />`storybook init --parser tsx`  |
| `--debug`                | Outputs more logs in the CLI to assist debugging.<br />`storybook init --debug`                                                                                                                |
| `--disable-telemetry`    | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook init --disable-telemetry`                                               |
| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook init --enable-crash-reports` |
| `--loglevel <level>`     | Controls level of logging during initialization.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`<br />`storybook init --loglevel debug`                  |
| `--logfile [path]`       | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.<br />`storybook init --logfile /tmp/debug-storybook.log`        |
| `--no-dev`               | Complete the initialization of Storybook without running the Storybook dev server.<br />`storybook init --no-dev`                                                                              |

### `add`

Installs a Storybook addon and configures your project for it. Read more in the [addon installation guide](https://storybook.js.org/docs/addons/install-addons.md).

```shell
storybook add [addon] [options]
```

Options include:

| Option                          | Description                                                                                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                  | Output usage information.<br />`storybook add --help`                                                                                                                                          |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook add --config-dir .storybook`                                                                                                                |
| `--package-manager`             | Sets the package manager to use when installing the addon.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook add [addon] --package-manager pnpm`              |
| `-s`, `--skip-postinstall`      | Skips post-install configuration. Used only when you need to configure the addon yourself.<br />`storybook add [addon] --skip-postinstall`                                                     |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook add --debug`                                                                                                                 |
| `--loglevel <level>`            | Controls level of logging during addon installation.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`<br />`storybook add [addon] --loglevel debug`       |
| `--logfile [path]`              | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.<br />`storybook add [addon] --logfile /tmp/debug-storybook.log` |

### `remove`

Deletes a Storybook addon from your project. Read more in the [addon installation guide](https://storybook.js.org/docs/addons/install-addons.md#removing-addons).

```shell
storybook remove [addon] [options]
```

Options include:

| Option                   | Description                                                                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-h`, `--help`           | Output usage information.<br />`storybook remove --help`                                                                                                                                         |
| `--package-manager`      | Sets the package manager to use when removing the addon.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook remove [addon]--package-manager pnpm`                |
| `--debug`                | Outputs more logs in the CLI to assist debugging.<br />`storybook remove --debug`                                                                                                                |
| `--disable-telemetry`    | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook remove --disable-telemetry`                                               |
| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook remove --enable-crash-reports` |

### `upgrade`

Upgrades your Storybook instance to the specified version (e.g., `@latest`, `@8`, `@next`). Read more in the [upgrade guide](https://storybook.js.org/docs/releases/upgrading.md).

```shell
storybook[@version] upgrade [options]
```

For example, `storybook@latest upgrade --dry-run` will perform a dry run (no actual changes) of upgrading your project to the latest version of Storybook.

Options include:

| Option                           | Description                                                                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                   | Output usage information.<br />`storybook upgrade --help`                                                                                                                                         |
| `-c, --config-dir <dir-name...>` | Directory or directories to find Storybook configurations<br />`storybook upgrade --config-dir .storybook`                                                                                        |
| `-n`, `--dry-run`                | Checks for version upgrades without installing them.<br />`storybook upgrade --dry-run`                                                                                                           |
| `-s`, `--skip-check`             | Skips the migration check step during the upgrade process.<br />`storybook upgrade --skip-check`                                                                                                  |
| `-y`, `--yes`                    | Skips interactive prompts and automatically upgrades Storybook to the latest version.<br />`storybook upgrade --yes`                                                                              |
| `-f`,`--force`                   | Force the upgrade, skipping autoblockers check.<br />`storybook upgrade --force`                                                                                                                  |
| `--package-manager`              | Sets the package manager to use when upgrading Storybook.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook upgrade --package-manager pnpm`                      |
| `--debug`                        | Outputs more logs in the CLI to assist debugging.<br />`storybook upgrade --debug`                                                                                                                |
| `--disable-telemetry`            | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook upgrade --disable-telemetry`                                               |
| `--enable-crash-reports`         | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook upgrade --enable-crash-reports` |
| `--logfile [path]`               | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.<br />`storybook upgrade --logfile /tmp/debug-storybook.log`        |
| `--loglevel <level>`             | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`).<br />`storybook upgrade --loglevel debug`                                                             |

### `migrate`

Runs the provided codemod to ensure your Storybook project is compatible with the specified version. Read more in the [migration guide](https://storybook.js.org/docs/releases/upgrading.md).

```shell
storybook[@version] migrate [codemod] [options]
```

The command requires the codemod name (e.g., `csf-2-to-3`) as an argument to apply the necessary
changes to your project. You can find the list of available codemods by running `storybook migrate
--list`.

For example, `storybook@latest migrate csf-2-to-3 --dry-run`, checks your project to verify if the codemod can be applied without making any changes, providing you with a report of which files would be affected.

Options include:

| Option                          | Description                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-h`, `--help`                  | Output usage information.<br />`storybook migrate --help`                                                                                                                                        |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook migrate --config-dir .storybook`                                                                                                              |
| `-n`, `--dry-run`               | Verify the migration exists and show the files to which it will be applied.<br />`storybook migrate --dry-run`                                                                                   |
| `-l`, `--list`                  | Shows a list of available codemods.<br />`storybook migrate --list`                                                                                                                              |
| `-g`, `--glob`                  | Glob for files upon which to apply the codemods.<br />`storybook migrate --glob src/**/*.stories.tsx`                                                                                            |
| `-p`, `--parser`                | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).<br />Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.<br />`storybook migrate --parser tsx` |
| `-r`, `--rename [from-to]`      | Renames the files affected by the codemod to include the provided suffix.<br />`storybook migrate --rename ".js:.ts"`                                                                            |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook migrate --debug`                                                                                                               |

### `automigrate`

Perform standard configuration checks to determine if your Storybook project can be automatically migrated to the specified version. Read more in the [migration guide](https://storybook.js.org/docs/releases/upgrading.md#automigrate-script).

```shell
storybook[@version] automigrate [fixId] [options]
```

For example, `storybook@latest automigrate --dry-run` scans your project for potential migrations that can be applied automatically without making any changes.

Options include:

| Option                          | Description                                                                                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                  | Output usage information.<br />`storybook automigrate --help`                                                                                                                                                             |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook automigrate --config-dir .storybook`                                                                                                                                   |
| `-n`, `--dry-run`               | Checks for available migrations without applying them.<br />`storybook automigrate --dry-run`                                                                                                                             |
| `-s`, `--skip-install`          | Skip installing dependencies whenever applicable.<br />`storybook automigrate --skip-install`                                                                                                                             |
| `-y`, `--yes`                   | Applies available migrations automatically without prompting for confirmation.<br />`storybook automigrate --yes`                                                                                                         |
| `-l`, `--list`                  | Shows a list of available automigrations.<br />`storybook automigrate --list`                                                                                                                                             |
| `--package-manager`             | Sets the package manager to use when running the auto migration.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook automigrate --package-manager pnpm`                                   |
| `--renderer`                    | Specifies Storybook's renderer to use when running the automigration.<br />Useful for monorepo environments where multiple Storybook instances can exist in the same project.<br />`storybook automigrate --renderer vue` |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook automigrate --debug`                                                                                                                                    |
| `--disable-telemetry`           | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook automigrate --disable-telemetry`                                                                   |
| `--enable-crash-reports`        | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook automigrate --enable-crash-reports`                     |

### `doctor`

Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when [upgrading](https://storybook.js.org/docs/releases/upgrading.md#automatic-health-check) Storybook versions.

```shell
storybook doctor [options]
```

Options include:

| Option                          | Description                                                                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                  | Output usage information.<br />`storybook doctor --help`                                                                                                                         |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook doctor --config-dir .storybook`                                                                                               |
| `--package-manager`             | Sets the package manager to use when running the health check.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook doctor --package-manager pnpm` |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook doctor --debug`                                                                                                |

### `ai`

Helpers for AI agents. The `ai` command exposes subcommands that generate AI-friendly instructions for automating Storybook tasks. See the [agentic setup docs](https://storybook.js.org/docs/ai/setup.md) for a full walkthrough.

```shell
storybook ai [options] [command]
```

Options include:

| Option                  | Description                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`          | Output usage information.<br />`storybook ai --help`                                                                      |
| `-o`, `--output <path>` | Write the prompt output to a file instead of printing it to stdout.<br />`storybook ai setup --output storybook-setup.md` |

#### `ai setup`

Generates a detailed, project-aware Markdown prompt that instructs an AI agent to configure Storybook in your project and write initial stories for real components. The prompt is built from your detected Storybook configuration (framework, renderer, builder, language, addons) and covers analyzing the codebase, configuring the preview, mocking side effects, writing stories, and verifying them with Vitest.

`storybook ai setup` is currently only available for projects using the React renderer with the Vite builder.

```shell
storybook ai setup [options]
```

Options include:

| Option                          | Description                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-h`, `--help`                  | Output usage information.<br />`storybook ai setup --help`                                                                                                                           |
| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook ai setup -c .storybook`                                                                                                           |
| `--package-manager <type>`      | Force package manager to use when detecting project information.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook ai setup --package-manager pnpm` |
| `--disable-telemetry`           | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook ai setup --disable-telemetry`                                 |
| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook ai setup --debug`                                                                                                  |
| `--loglevel [level]`            | Controls level of logging.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.<br />`storybook ai setup --loglevel warn`                          |
| `--logfile [path]`              | Write debug logs to a file.<br />`storybook ai setup --logfile ./sb.log`                                                                                                             |

When run without `--output`, the generated prompt is printed to stdout. This is how AI agents typically consume it, by running the command directly and reading the result. When run with `--output`, the prompt is written to the given file path so you can paste or attach it to an agent that doesn't have shell access.

### `info`

Reports useful debugging information about your environment. Helpful in providing information when opening an issue or a discussion.

```shell
storybook info
```

Example output:

```shell
Storybook Environment Info:

  System:
    OS: macOS 14.2
    CPU: (8) arm64 Apple M3
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 18.19.0 - ~/.nvm/versions/node/v18.19.0/bin/node
    npm: 10.2.3 - ~/.nvm/versions/node/v18.19.0/bin/npm <----- active
  Browsers:
    Chrome: 120.0.6099.199
  npmPackages:
    @storybook/addon-onboarding: ^1.0.10 => 1.0.10
    @storybook/react: ^7.6.6 => 7.6.6
    @storybook/react-vite: ^7.6.6 => 7.6.6
    storybook: ^7.6.6 => 7.6.6
  npmGlobalPackages:
    chromatic: ^10.2.0 => 10.2.0
```

### `index`

Build an `index.json` that lists all stories and docs entries in your Storybook.

```shell
storybook index [options]
```

Options include:

| Option                            | Description                                            |
| --------------------------------- | ------------------------------------------------------ |
| `-o`, `--output-file <file-name>` | JSON file to output index                              |
| `-c`, `--config-dir <dir-name>`   | Storybook configuration directory                      |
| `--quiet`                         | Suppress verbose build output                          |
| `--loglevel <level>`              | Control level of logging during build                  |
| `--disable-telemetry`             | Disables Storybook's telemetry                         |
| `--debug`                         | Outputs more logs in the CLI to assist debugging.      |
| `--enable-crash-reports`          | Enables sending crash reports to Storybook's telemetry |

### `sandbox`

Generates a local sandbox project using the specified version (e.g., `@latest`, `@8`, `@next`) for testing Storybook features based on the list of supported [frameworks](https://storybook.js.org/docs/configure/integration/frameworks.md). Useful for reproducing bugs when opening an issue or a discussion.

```shell
storybook[@version] sandbox [framework-filter] [options]
```

For example, `storybook@next sandbox` will generated sandboxes using the newest pre-release version of Storybook.

The `framework-filter` argument is optional and can filter the list of available frameworks. For example, `storybook@next sandbox react` will only offer to generate React-based sandboxes.

Options include:

| Option                      | Description                                                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`              | Output usage information.<br />`storybook sandbox --help`                                                                                                                                         |
| `-o`, `--output [dir-name]` | Configures the location of the sandbox project.<br />`storybook sandbox --output /my-sandbox-project`                                                                                             |
| `--no-init`                 | Generates a sandbox project without initializing Storybook.<br />`storybook sandbox --no-init`                                                                                                    |
| `--debug`                   | Outputs more logs in the CLI to assist debugging.<br />`storybook sandbox --debug`                                                                                                                |
| `--disable-telemetry`       | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`storybook sandbox --disable-telemetry`                                               |
| `--enable-crash-reports`    | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`storybook sandbox --enable-crash-reports` |

If you're looking for a hosted version of the available sandboxes, see
[storybook.new](https://storybook.new).

## `create-storybook`

To streamline the process of creating a new Storybook project, a separate CLI called `create-storybook` is provided. Package managers such as npm, pnpm, and Yarn will execute this command when running `create storybook`. You can specify a version (e.g., `@latest`, `@8`, `@next`) or it will default to the latest version. Read more in the [installation guide](https://storybook.js.org/docs/get-started/install.md).

```shell
create storybook[@version] [options]
```

For example, `create storybook@8.6` will install Storybook 8.6 into your project.

Options include:

| Option                   | Description                                                                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-h`, `--help`           | Output usage information.<br />`create storybook --help`                                                                                                                                         |
| `-b`, `--builder`        | Defines the [builder](https://storybook.js.org/docs/builders.md) to use for your Storybook instance.<br />`create storybook --builder webpack5`                                                                      |
| `-f`, `--force`          | Forcefully installs Storybook into your project, prompting you to overwrite existing files.<br />`create storybook --force`                                                                      |
| `-s`, `--skip-install`   | Skips the dependency installation step. Used only when you need to configure Storybook manually.<br />`create storybook --skip-install`                                                          |
| `-t`, `--type`           | Defines the [framework](https://storybook.js.org/docs/configure/integration/frameworks.md) to use for your Storybook instance.<br />`create storybook --type solid`                                                        |
| `-y`, `--yes`            | Skips interactive prompts and automatically installs Storybook per specified version, including all features.<br />`create storybook --yes`                                                      |
| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated.<br />`create storybook --features docs test a11y`                     |
| `--package-manager`      | Sets the package manager to use when installing Storybook.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`create storybook --package-manager pnpm`                     |
| `--use-pnp`              | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager.<br />`create storybook --use-pnp`               |
| `-p`, `--parser`         | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).<br />Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.<br />`create storybook --parser tsx`  |
| `--debug`                | Outputs more logs in the CLI to assist debugging.<br />`create storybook --debug`                                                                                                                |
| `--disable-telemetry`    | Disables Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out).<br />`create storybook --disable-telemetry`                                               |
| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](https://storybook.js.org/docs/configure/telemetry.md#crash-reports-disabled-by-default).<br />`create storybook --enable-crash-reports` |
| `--loglevel <level>`     | Controls level of logging during initialization.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`<br />`create storybook --loglevel debug`                  |
| `--logfile [path]`       | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.<br />`create storybook --logfile /tmp/debug-storybook.log`        |
| `--no-dev`               | Complete the initialization of Storybook without running the Storybook dev server.<br />`create storybook --no-dev`                                                                              |
> Source: https://storybook.js.org/docs/api/cli-options
---

# How we release Storybook

Storybook packages ([`storybook`](https://www.npmjs.com/package/storybook) and everything under the [`@storybook` organization](https://www.npmjs.com/org/storybook)) follow [Semantic Versioning](https://semver.org/) (semver). We have a structured release process to ensure stability, compatibility, and a smooth upgrade path for users. This page outlines our release channels, supported versions, and the cadence of major, minor, patch, and pre releases.

## Release Channels

We publish releases on two channels. You can install a specific channel via npm tags:

- **Stable channel** (`latest`): Installs the latest stable release.

```bash
npm create storybook@latest
```

- **Pre-release channel** (`next`): Installs the latest [pre-release](#pre-release).

```bash
npm create storybook@next
```

## Supported Versions

We actively maintain the latest major version of Storybook. Within the current major, we patch only the latest minor version. Most fixes and new work go into the next minor (or sometimes major) and are not backported. Critical security fixes may be backported more broadly based on severity:

- Latest major: Receives all security fixes
- Previous two majors: Receive security patches for **High or Critical [CVSS vulnerabilities](https://en.wikipedia.org/wiki/Common_Vulnerability_Scoring_System) only**
- Older versions: No longer receive any patches

For example, if the latest version is `10.2.1`:

- We support `10.x.x` versions and release `10.2.x` patch versions
- Most fixes and new work will be released as `10.3.0-alpha.x` versions
  - If the next release is a major version, it would be `11.0.0-alpha.x`
- We will backport **High or Critical** security fixes to the latest minor of `9.x.x` and `8.x.x`
- Versions `7.x.x` and older will not receive security patches

For compatibility with other libraries and tools in the JavaScript ecosystem, please refer to the [compatibility tracker](https://github.com/storybookjs/storybook/issues/23279).

## Release Cycle

### Major Release

**Cadence**: Roughly once per year

**Channel**: Stable (`latest`)

Major releases introduce breaking changes and significant new features. We use major releases to keep up with ecosystem changes, evolve Storybook’s architecture and APIs, and make the tool faster, leaner, and easier to use.

Once we start working on a major release, we pause minor releases but continue to ship patch releases as needed. Major releases go through a sequence of [pre-releases](#pre-release)—`alpha`, `beta`, and `rc` (release candidate)—before landing in the stable channel. We aim to include automated migrations and provide [a comprehensive migration guide](https://storybook.js.org/docs/releases/migration-guide.md) when manual changes are necessary.

Storybook versions prior to 7 had a very different architecture. As a result, upgrading from v6 to newer versions can be more challenging. Starting in v7, we’ve focused heavily on smoother migrations. Upgrades from v7 to v8, and v8 to v9 (and beyond), should feel significantly easier thanks to automigrations and better tooling.

### Minor Release

**Cadence**: Roughly every 8 weeks

**Channel**: Stable (`latest`)

Minor releases deliver new features, enhancements, and non-breaking improvements. Each minor release may be preceded by an alpha [pre-release](#pre-release) (e.g. `x.y.0-alpha`).

### Patch Release

**Cadence**: as needed (only for the current minor)

**Channel**: Stable (`latest`)

Patch releases include critical bug fixes and security updates. These are issued only for the current minor version and are not pre-released.

### Pre-release

**Cadence**: Regularly

**Channel**: Pre-release (`next`)

Pre-releases are created to gather early feedback and ensure stability before an official release. Minor version stable releases are preceded by pre-releases with an `alpha` tag (e.g. `x.y.0-alpha`), with no patch pre-releases. Major version stable releases are preceded by a fuller cycle of `alpha`, `beta`, and `rc` pre-releases before the final release.
> Source: https://storybook.js.org/docs/releases
---

# Migration guide for Storybook 10

[full-migration-notes]: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-9x-to-1000

Storybook 10 is a breaking maintenance release focused on ESM-only package distribution. Its main features include:

- 💎 ESM-only to reduce install size
- ↗️ CSF Next preview with better typesafety and autocompletion
- 🏷 Improved tags-based filtering

Coming soon:

- 🧪 Familiar and ergonomic CSF test functions (experimental)

This guide is meant to help you **upgrade from Storybook 9.x to 10** successfully!

**Migrating from a Storybook version prior to 9?**

You'll first need to [upgrade to Storybook 9](https://storybook.js.org/docs/releases/migration-guide-from-older-version.md). Then you can return to this guide.

## Major breaking changes

The rest of this guide will help you upgrade successfully, either automatically or manually. But first, there are some [breaking changes][full-migration-notes] in Storybook 10. Here are the most impactful changes you should know about before you go further:

- [Main configuration (`.storybook/main.js|ts`) and other presets must be valid ESM](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#the-storybookmain-file-and-other-presets-must-be-valid-esm)
- Ecosystem updates
  - [Node 20.19+ or 22.12+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nodejs-2019-or-2212-required)

If any of these changes apply to your project, please read through the linked migration notes before continuing.

If any of these new requirements or changes are blockers for your project, we recommend to continue using Storybook 8.x.

You may wish to read the [full migration notes][full-migration-notes] before migrating. Or you can run the upgrade command below and we’ll try to take care of everything for you!

## Automatic upgrade

To upgrade your Storybook, run the [upgrade](https://storybook.js.org/docs/releases/upgrading.md) command in the root of your repository:

```shell
npx storybook@latest upgrade
```

```shell
pnpm dlx storybook@latest upgrade
```

```shell
yarn dlx storybook@latest upgrade
```

This will:

1. Find all of the Storybook projects in your repository
2. For each project
   1. Determine that none of the [breaking changes](#major-breaking-changes) apply to your project
      - If they do, you will receive instructions on how to resolve them before continuing
   2. Upgrade your Storybook dependencies to the latest version
   3. Run a collection of _automigrations_, which will:
      - Check for common upgrade tasks
      - Explain the necessary changes with links to more information
      - Ask for approval, then perform the task automatically on your behalf

## New projects

To add Storybook to a project that isn’t currently using Storybook:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

This will:

1. Figure out which renderer (React, Vue, Angular, Web Components), builder (Webpack, Vite), or meta-framework (Next.js, SvelteKit) you’re using
2. Install Storybook 10 and auto-configure it to mirror project settings

## Troubleshooting

The automatic upgrade should get your Storybook into a working state. If you encounter an error running Storybook after upgrading, here’s what to do:

1. Try running the [`doctor` command](https://storybook.js.org/docs/api/cli-options.md#doctor) to check for common issues (such as duplicate dependencies, incompatible addons, or mismatched versions) and see suggestions for fixing them.
2. If you’re running `storybook` with the `dev` command, try using the `build` command instead. Sometimes `build` errors are more legible than `dev` errors!
3. Check [the full migration notes][full-migration-notes], which contains an exhaustive list of noteworthy changes in Storybook 10. Many of these are already handled by automigrations when you upgrade, but not all are. It’s also possible that you’re experiencing a corner case that we’re not aware of.
4. Search [Storybook issues on GitHub](https://github.com/storybookjs/storybook/issues). If you’re seeing a problem, there’s a good chance other people are too. If so, upvote the issue, try out any workarounds described in the comments, and comment back if you have useful info to contribute.
5. If there’s no existing issue, you can [file one](https://github.com/storybookjs/storybook/issues/new/choose), ideally with a reproduction attached. We’ll be on top of Storybook 10 issues as we’re stabilizing the release.

If you prefer to debug yourself, here are a few useful things you can do to help narrow down the problem:

1. Try removing all addons that are not in the `@storybook` npm namespace (make sure you don't remove the `storybook` package). Community addons that work well with 9.x might not yet be compatible with 10.x, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 10, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!
2. Another debugging technique is to bisect to older prerelease versions of Storybook to figure out which release broke your Storybook. For example, assuming that the current prerelease of Storybook is `10.0.0-beta.56`, you could set the version to `10.0.0-alpha.0` in your `package.json` and reinstall to verify that it still works (`alpha.0` should be nearly identical to `9.1.x`). If it works, you could then try `10.0.0-beta.0`, then `10.0.0-beta.28` and so forth. Once you’ve isolated the bad release, read through its [CHANGELOG](https://github.com/storybookjs/storybook/blob/next/CHANGELOG.prerelease.md) entry and perhaps there’s a change that jumps out as the culprit. If you find the problem, please submit an issue or pull request to the Storybook monorepo and we’ll do our best to take care of it quickly.

## Optional migrations

In addition to the automigrations and manual migrations above, there are also optional migrations that you should consider. These are features that we’ve deprecated in Storybook 10 (but remain backwards compatible), or best practices that should help you be more productive in the future.

### `test-runner` to `addon-vitest`

`addon-vitest` and the rest of the [Storybook Test experience](https://storybook.js.org/blog/storybook-test-sneak-peek/) is designed to supercede the `test-runner`. It's faster and provides a better experience for writing and running tests. If your project uses React, Vue, or Svelte and is built with Vite, you should consider migrating to `addon-vitest`, by following the [installation instructions](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#automatic-setup).
> Source: https://storybook.js.org/docs/releases/migration-guide
---

# Migration guide from Storybook 8.x to 9.1

[full-migration-notes]: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-8x-to-900

Storybook 9 improves performance, compatibility, and stability. Its key features include:

- 🔋 Storybook Test, a batteries-included testing tool in your Storybook
- 🧪 Component testing
- ♿️ Accessibility testing
- 🛡️ Test coverage
- 🪶 48% lighter bundle
- ⚛️ React Native for device and web
- 🏷️ Tags-based story organization

This guide is meant to help you **upgrade from Storybook 8.x to 9.1** successfully!

**Migrating from Storybook 6 or 7?**

We have prior migration guides for:

- [Storybook 7.x to 8.x](https://storybook.js.org/docs/8/migration-guide.md)
- [Storybook 6.x to 8.x](https://storybook.js.org/docs/8/migration-guide/from-older-version.md)

## Major breaking changes

The rest of this guide will help you upgrade successfully, either automatically or manually. But first, there are some [breaking changes][full-migration-notes] in Storybook 9. Here are the most impactful changes you should know about before you go further:

- [Packages have been consolidated/removed](#package-structure-changes)
- [Essential addons moved to core](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#essentials-addons-viewport-controls-interactions-and-actions-moved-to-core)
- [Test addon renamed from `experimental-addon-test` to `addon-vitest`](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#experimental-test-addon-stabilized-and-renamed)
- [`nextjs-vite` framework stabilized](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nextjs-vite-builder-stabilized)
- [Removed Webpack builder support for Preact, Vue, and Web Components in favor of Vite](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropped-webpack5-builder-support-in-favor-of-vite)
- [Manager builder removed alias for `util`, `assert` and `process`](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#manager-builder-removed-alias-for-util-assert-and-process)
- Ecosystem updates
  - [Node 20+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nodejs--20)
  - [Angular 18+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#angular-require-v18-and-up)
  - [Lit v3+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#lit--require-v3-and-up)
  - [Next.js 14+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nextjs-require-v14-and-up)
  - [Svelte 5+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#svelte-require-v5-and-up)
  - [Vite 5+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#vite-4)
  - [Vitest 3+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#vitest-addon-former-storybookexperimental-addon-test-vitest-20-support-is-dropped)
  - [npm 10+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#package-managers)
  - [pnpm 9+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#package-managers)
  - [yarn 4+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#package-managers)
  - [TypeScript 4.9+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#typescript--49)

If any of these changes apply to your project, please read through the linked migration notes before continuing.

If any of these new requirements or changes are blockers for your project, we recommend to continue using Storybook 8.x.

You may wish to read the [full migration notes][full-migration-notes] before migrating. Or you can run the upgrade command below and we’ll try to take care of everything for you!

## Automatic upgrade

To upgrade your Storybook, run the [upgrade](https://storybook.js.org/docs/releases/upgrading.md) command in the root of your repository:

```shell
npx storybook@latest upgrade
```

```shell
pnpm dlx storybook@latest upgrade
```

```shell
yarn dlx storybook@latest upgrade
```

This will:

1. Find all of the Storybook projects in your repository
2. For each project
   1. Determine that none of the [breaking changes](#major-breaking-changes) apply to your project
      - If they do, you will receive instructions on how to resolve them before continuing
   2. Upgrade your Storybook dependencies to the latest version
   3. Run a collection of _automigrations_, which will:
      - Check for common upgrade tasks
      - Explain the necessary changes with links to more information
      - Ask for approval, then perform the task automatically on your behalf

## New projects

To add Storybook to a project that isn’t currently using Storybook:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook
```

This will:

1. Figure out which renderer (React, Vue, Angular, Web Components), builder (Webpack, Vite), or meta-framework (Next.js, SvelteKit) you’re using
2. Install Storybook 9 and auto-configure it to mirror project settings

## Troubleshooting

The automatic upgrade should get your Storybook into a working state. If you encounter an error running Storybook after upgrading, here’s what to do:

1. Try running the [`doctor` command](https://storybook.js.org/docs/api/cli-options.md#doctor) to check for common issues (such as duplicate dependencies, incompatible addons, or mismatched versions) and see suggestions for fixing them.
2. If you’re running `storybook` with the `dev` command, try using the `build` command instead. Sometimes `build` errors are more legible than `dev` errors!
3. Check [the full migration notes][full-migration-notes], which contains an exhaustive list of noteworthy changes in Storybook 9. Many of these are already handled by automigrations when you upgrade, but not all are. It’s also possible that you’re experiencing a corner case that we’re not aware of.
4. Search [Storybook issues on GitHub](https://github.com/storybookjs/storybook/issues). If you’re seeing a problem, there’s a good chance other people are too. If so, upvote the issue, try out any workarounds described in the comments, and comment back if you have useful info to contribute.
5. If there’s no existing issue, you can [file one](https://github.com/storybookjs/storybook/issues/new/choose), ideally with a reproduction attached. We’ll be on top of Storybook 9 issues as we’re stabilizing the release.

If you prefer to debug yourself, here are a few useful things you can do to help narrow down the problem:

1. Try removing all addons that are not in the `@storybook` npm namespace (make sure you don't remove the `storybook` package). Community addons that work well with 8.x might not yet be compatible with 9.x, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 9, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!
2. Another debugging technique is to bisect to older prerelease versions of Storybook to figure out which release broke your Storybook. For example, assuming that the current prerelease of Storybook is `9.0.0-beta.56`, you could set the version to `9.0.0-alpha.0` in your `package.json` and reinstall to verify that it still works (`alpha.0` should be nearly identical to `8.6.x`). If it works, you could then try `9.0.0-beta.0`, then `9.0.0-beta.28` and so forth. Once you’ve isolated the bad release, read through its [CHANGELOG](https://github.com/storybookjs/storybook/blob/next/CHANGELOG.prerelease.md) entry and perhaps there’s a change that jumps out as the culprit. If you find the problem, please submit an issue or pull request to the Storybook monorepo and we’ll do our best to take care of it quickly.

## Package structure changes

The following packages are no longer published. Instead they have been consolidated into Storybook's core package, `storybook`. If a consolidated package had exports, those are available via the replacement path in the table below. See the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropped-support-for-legacy-packages) for details.

| Removal                         | Replacement             |
| ------------------------------- | ----------------------- |
| `@storybook/addon-actions`      | `storybook/actions`     |
| `@storybook/addon-backgrounds`  | N/A                     |
| `@storybook/addon-controls`     | N/A                     |
| `@storybook/addon-highlight`    | `storybook/highlight`   |
| `@storybook/addon-interactions` | N/A                     |
| `@storybook/addon-measure`      | N/A                     |
| `@storybook/addon-outline`      | N/A                     |
| `@storybook/addon-toolbars`     | N/A                     |
| `@storybook/addon-viewport`     | `storybook/viewport`    |
| `@storybook/manager-api`        | `storybook/manager-api` |
| `@storybook/preview-api`        | `storybook/preview-api` |
| `@storybook/test`               | `storybook/test`        |
| `@storybook/theming`            | `storybook/theming`     |

The following packages have been consolidated and moved into an internal path to indicate that they are now for internal usage only. They will continue to work in `9.x` releases, but will likely be removed in `10.0`. See the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropped-support-for-legacy-packages) for details.

| Deprecation                  | Replacement                          |
| ---------------------------- | ------------------------------------ |
| `@storybook/builder-manager` | `storybook/internal/builder-manager` |
| `@storybook/channels`        | `storybook/internal/channels`        |
| `@storybook/client-logger`   | `storybook/internal/client-logger`   |
| `@storybook/components`      | `storybook/internal/components`      |
| `@storybook/core-common`     | `storybook/internal/common`          |
| `@storybook/core-events`     | `storybook/internal/core-events`     |
| `@storybook/core-server`     | `storybook/internal/core-server`     |
| `@storybook/csf-tools`       | `storybook/internal/csf-tools`       |
| `@storybook/docs-tools`      | `storybook/internal/docs-tools`      |
| `@storybook/manager`         | `storybook/internal/manager`         |
| `@storybook/node-logger`     | `storybook/internal/node-logger`     |
| `@storybook/preview`         | `storybook/internal/preview`         |
| `@storybook/router`          | `storybook/internal/router`          |
| `@storybook/telemetry`       | `storybook/internal/telemetry`       |
| `@storybook/types`           | `storybook/internal/types`           |

Addon authors may continue to use the internal packages, there is currently not yet any replacement.

## Optional migrations

In addition to the automigrations and manual migrations above, there are also optional migrations that you should consider. These are features that we’ve deprecated in Storybook 9 (but remain backwards compatible), or best practices that should help you be more productive in the future.

### `test-runner` to `addon-vitest`

`addon-vitest` and the rest of the [Storybook Test experience](https://storybook.js.org/blog/storybook-test-sneak-peek/) is designed to supercede the `test-runner`. It's faster and provides a better experience for writing and running tests. If your project uses React, Vue, or Svelte and is built with Vite, you should consider migrating to `addon-vitest`, by following the [installation instructions](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon/index.md#automatic-setup).

### CSF 2 to CSF 3

There are [many good reasons](/blog/storybook-csf3-is-here/) to convert your stories from CSF 2 to CSF 3. We provide a codemod which, in most cases, should automatically make the code changes for you (make sure to update the glob to fit your files):

```sh
# Convert CSF 2 to CSF 3
npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx
```

```sh
# Convert CSF 2 to CSF 3
pnpm dlx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx
```

```sh
# Convert CSF 2 to CSF 3
yarn dlx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx
```
> Source: https://storybook.js.org/docs/releases/migration-guide-from-older-version
---

# Upgrading Storybook

The frontend ecosystem is a fast-moving place. Regular dependency upgrades are a way of life, whether upgrading a framework, library, tooling, or all of the above! Storybook provides a few resources to help ease the pain of upgrading.

## Upgrade script

The most common upgrade is Storybook itself. [Storybook releases](https://storybook.js.org/releases) follow [Semantic Versioning](https://semver.org/). We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months, and major versions of Storybook with breaking changes roughly once per year.

To help ease the pain of keeping Storybook up-to-date, we provide a command-line script that automatically detects all Storybook projects in your repository:

```shell
npx storybook@latest upgrade
```

```shell
pnpm dlx storybook@latest upgrade
```

```shell
yarn dlx storybook@latest upgrade
```

**Important:** Always run the upgrade command from your repository root. The script will automatically detect all Storybook projects in your repository, including in mono-repository setups.

The `upgrade` command will use whichever version you specify. For example:

- `storybook@latest upgrade` will upgrade to the latest version
- `storybook@8.6.1 upgrade` will upgrade to `8.6.1`
- `storybook@9 upgrade` will upgrade to the newest `9.x.x` version

The `upgrade` command is designed to upgrade from one major version to the next.

- ✅ OK: Using Storybook 8 and running `storybook@9 upgrade`
- ❌ Not OK: Using Storybook 7 and running `storybook@9 upgrade`

If you want to upgrade across more than major version, run the command multiple times. For example, to upgrade from Storybook 7 to Storybook 9, you first need to upgrade to the latest version of Storybook 8 with `storybook@8 upgrade`, and then run `storybook@9 upgrade` to upgrade to the latest version of Storybook 9.

The only exception to this is when upgrading from 6 to 8, where you can run `storybook@8 upgrade` directly to upgrade from 6.x.x to 8.x.x.

### Mono-repository support

The upgrade script provides enhanced support for mono-repositories:

- **Automatic detection**: The script automatically detects all Storybook projects in your repository
- **Selective upgrades**: If your Storybooks are truly encapsulated (meaning each Storybook project has its own independent Storybook dependencies in its own `package.json`), you can select which Storybook project to upgrade
- **Bulk upgrades**: If your Storybooks share dependencies, all detected projects will be upgraded together to ensure consistency

#### Limiting scope in large mono-repositories

For large mono-repositories where you want to limit the upgrade to a specific directory, use the `STORYBOOK_PROJECT_ROOT` environment variable:

```bash
STORYBOOK_PROJECT_ROOT=./packages/frontend storybook@latest upgrade
```

This is especially helpful in huge mono-repositories with semi-encapsulated Storybooks.

## Upgrade process

After running the command, the script will:

- Detect all Storybook projects in your repository
- Upgrade all Storybook packages to the specified version
- Run the relevant [automigrations](https://storybook.js.org/docs/releases/migration-guide.md#automatic-upgrade) factoring in the [breaking changes](https://storybook.js.org/docs/releases/migration-guide.md#major-breaking-changes) between your current version and the specified version
- Automatically run the [doctor command](#automatic-health-check) to verify the upgrade

In addition to running the command, we also recommend checking the [MIGRATION.md file](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md), for the detailed log of relevant changes and deprecations that might affect your upgrade.

### Automatic health check

The upgrade script automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions.

The health check runs automatically for all detected Storybooks. You can also run it manually at any time using the `storybook doctor` command:

```shell
npx storybook@latest doctor
```

```shell
pnpm dlx storybook@latest doctor
```

```shell
yarn dlx storybook@latest doctor
```

### Error handling and debugging

If you encounter issues during the upgrade:

1. A `debug-storybook.log` file will be created in the repository root containing all relevant logs
2. For more detailed information, set the log level to `debug` using the `--loglevel debug` flag
3. Create a GitHub issue with the logs if you need help resolving the problem

## Command-line options

The upgrade command supports several flags to customize the upgrade process:

```bash
storybook@latest upgrade [options]
```

### Available flags

| Flag                             | Description                                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `-c, --config-dir <dir-name...>` | Directory or directories to find Storybook configurations                                                                      |
| `--debug`                        | Enable more logs for debugging (default: false)                                                                                |
| `--disable-telemetry`            | Disable sending telemetry data                                                                                                 |
| `--enable-crash-reports`         | Enable sending crash reports to telemetry data                                                                                 |
| `-f, --force`                    | Force the upgrade, skipping autoblockers                                                                                       |
| `--loglevel <level>`             | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`)                                     |
| `--package-manager <manager>`    | Force package manager: `npm`, `pnpm`, `yarn1`, `yarn2`, or `bun`                                                               |
| `-s, --skip-check`               | Skip postinstall version and automigration checks                                                                              |
| `--logfile [path]`               | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided. |
| `-y, --yes`                      | Skip prompting the user                                                                                                        |

### Example usage

```bash
# Upgrade with logging for debugging
storybook@latest upgrade --loglevel debug --logfile debug-storybook.log

# Force upgrade without prompts
storybook@latest upgrade --force --yes

# Upgrade specific config directories only
storybook@latest upgrade --config-dir .storybook-app .storybook-ui
```

## Automigrate script

Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example well-known frontend frameworks, such as [Angular](https://update.angular.io/?l=2&v=16.0-17.0), [Next.js](https://nextjs.org/docs/pages/building-your-application/upgrading) or [Svelte](https://svelte.dev/docs/v4-migration-guide) have been rolling out significant changes to their ecosystem, so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for:

```shell
npx storybook@latest automigrate
```

```shell
pnpm dlx storybook@latest automigrate
```

```shell
yarn dlx storybook@latest automigrate
```

It runs a set of standard configuration checks, explains what is potentially out-of-date, and offers to fix it for you automatically. It also points to the relevant documentation so you can learn more. It runs automatically as part of [`storybook upgrade`](#upgrade-script) command, but it's also available on its own if you don't want to upgrade Storybook.

## Prereleases

In addition to the above, Storybook is under constant development, and we publish pre-release versions almost daily. Pre-releases are the best way to try out new features before they are generally available, and we do our best to keep them as stable as possible, although this is not always possible.

To upgrade to the latest pre-release:

```shell
npx storybook@next upgrade
```

```shell
pnpm dlx storybook@next upgrade
```

```shell
yarn dlx storybook@next upgrade
```

The `upgrade` command will use whichever version you specify. For example:

- `storybook@next upgrade` will upgrade to the newest pre-release version
- `storybook@8.0.0-beta.1 upgrade` will upgrade to `8.0.0-beta.1`
- `storybook@8 upgrade` will upgrade to the newest `8.x` version

If you'd like to downgrade to a stable version, manually edit the package version numbers in your `package.json` and re-install.

Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](https://storybook.js.org/docs/configure/telemetry.md#how-to-opt-out) if you'd not like to share any information.

## Troubleshooting

### Storybook doesn't detect my Storybook project

By default, the upgrade script will attempt to find Storybook configuration in `.storybook` directories in your repository. If your Storybook configuration is located in a different directory, you can specify it using the `--config-dir` flag.

The `--config-dir` flag can accept multiple directories.

```bash
storybook@latest upgrade --config-dir .storybook-app .storybook-ui
```

If your project can be detected, but you get an error during the detection process, please check the `debug-storybook.log` file in the root of your repository. It will contain the full output of the detection process and will help you troubleshoot the issue.

### Storybook doesn't automigrate non-Storybook files

Our automigrations usually only transform and migrate files inside of your `.storybook` directory and your story and mdx files, which are mentioned as part of the Storybook configuration.

If you have other files that contain Storybook-specific code, you might need to manually migrate them.
> Source: https://storybook.js.org/docs/releases/upgrading
---

# Features Lifecycle

This page explains how the Storybook team classifies features using four lifecycle labels: **Experimental**, **Preview**, **Stable**, and **Deprecated**.

These labels help users understand our level of commitment, the expected quality, likelihood of breaking changes, and anticipated timeline for each feature. By making this process transparent, we aim to support better adoption decisions and build trust in how Storybook evolves.

## Experimental

This stage marks the beginning of a feature’s development, where we’re validating ideas and shaping direction.

Experimental features are functional but still evolving, with room for iteration based on real-world use. They’re ideal for trying out in prototypes or early integrations, not yet something to build critical paths around. Each experimental feature comes with an [RFC](https://github.com/storybookjs/storybook/discussions/categories/rfc) where we share the initial idea and report progress. We strongly encourage feedback to help guide the next steps.

During this stage, we’re committed to fully exploring the concept. As such, specific implementation details may change significantly before stabilization.

## Preview

Preview features are nearly production-ready and generally reliable, with documentation in place and most known issues addressed. They should be fully functional for at least one supported framework, but may still be incomplete or less polished in others. These features are suitable for use in real projects, and we encourage teams to adopt them and share feedback.

While the feature is stable in direction, we may introduce minimal breaking changes in minor releases to address gaps or refine behavior. In those cases, we provide automigrations where possible to ease the transition. We aim to collect feedback and iterate for 1-2 minor releases before promoting to stable.

## Stable

Stable features are fully supported and safe for production use across all projects. They are well-documented, thoroughly tested in all of our core frameworks, and follow [semantic versioning](https://semver.org). Users can expect long-term support, with any breaking changes reserved for major releases.

## Deprecated

Deprecated features are in the process of being phased out and will be removed in an upcoming major release. Users should begin migrating to supported alternatives as soon as possible. These features no longer receive active development or bug fixes, and their functionality may degrade over time. While they may still work, they should not be used for new development.

Typically, a deprecated feature is removed within the next major release cycle (for example, if deprecated in 8.x, removal is expected in 9.0).
> Source: https://storybook.js.org/docs/releases/features
---

# Roadmap

The Storybook team maintains a [public roadmap](https://github.com/orgs/storybookjs/projects/20/views/1) in the form of a GitHub project. This page explains what's in the roadmap, how to interpret it, and how to contribute to it.

## What's in the roadmap?

Each card represents a Storybook project. The columns represent how larger changes make their way from idea to shipped feature. Projects typically start as an [Request for Comment (RFC)](https://storybook.js.org/docs/contribute/RFC.md), then evolve into a [tracking issue](https://github.com/storybookjs/storybook/issues?q=is%3Aissue++sort%3Aupdated-desc+label%3ATracking+) once the team has fully scoped what it entails. We ship a Storybook [minor version](https://semver.org/) every eight weeks, and a major version once per year, typically in Feb/Mar.

### Candidates

These cards are ideas on our radar that we are considering for the current major release. For example, if `8.0` is the most recent major version, these would be ideas for `8.x` or `9.0`. The ideas in this column are the fuzziest and may come and go depending on our priorities.

### Under consideration

These are projects being discussed for the next dev cycle. For example, if the most recent minor version is `8.1`, and we are currently working on `8.2`, the projects in this column would be under consideration for `8.3`. Unlike the candidates column, which can contain any idea, the projects under consideration must be documented with an [RFC](https://storybook.js.org/docs/contribute/RFC.md).

### In progress

These are projects that we are currently working on. There are two kinds of projects in this column:

1. **[Tracking issues](https://github.com/storybookjs/storybook/issues?q=is%3Aissue++sort%3Aupdated-desc+label%3ATracking+)**: Fully scoped projects expected to ship in the next minor release. For example, if the most recent minor is `8.1`, these should ship in `8.2`, eight weeks after `8.1`.
2. **Other projects**: Community projects facilitated by the core team and side projects. These don't have an ETA but we will push to have them ready as part of the current major. For example, if `8.0` is the most recent major version, these should ship in `8.x` or `9.0`.

### Done

These projects are completed, documented, and released. We follow a "fixed time, variable scope" policy for core projects, which means we scope a project into milestones to provide the most value to users as early as possible and cut scope if necessary to ship on time. If a feature has been scoped out of a project, we might try to fit it into a follow-up project, treat it as general maintenance work, or forget about it. Storybook is open source, so PR contributions are always welcome!

## Frequently asked questions

### When will project X be available?

This roadmap is an estimation, not a commitment. In general, every tracking issue "in progress" should be available in the next two months. Everything else on the board has a decent chance of getting into the next major release. For example, if `8.0` is the most recent major release, we will try to ship everything on the board as part of `8.x` or `9.0`. If we don't think a project is likely for the next major, we will kick it off the board.

### What about issue Y or discussion Z?

The Storybook core team and our community members continuously contribute bug fix bugs and smaller product improvements. The projects here are larger chunks of work. In some cases they may close out certain issues, and when possible we will call those out in the RFC or project tracking issue.

### How do I get something onto the board?

If there's a significant product improvement that you want to see, and there is currently an issue or an [RFC](https://storybook.js.org/docs/contribute/RFC.md) for it, upvote that issue/discussion, and comment on it with more information about your need or use case if it's not currently captured. If you don't see anything that's quite right, please feel free to [submit an RFC](https://github.com/storybookjs/storybook/discussions/new?category=rfc). We prioritize based on a combination of user/contributor interest (upvotes, comments, [Discord](https://discord.gg/storybook) conversations, etc.) and our own strategic ambitions for the project.
> Source: https://storybook.js.org/docs/releases/roadmap
---

# How to contribute

Storybook is a community-oriented open source project that welcomes contributions. Some of our most popular features started with a developer wanting to solve a problem for themselves.

## Contributor covenant

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. [Continue reading our contributor covenant »](https://github.com/storybookjs/storybook/blob/next/CODE_OF_CONDUCT.md)

## Ways to contribute

- [**RFC process**](https://storybook.js.org/docs/contribute/RFC.md) for authoring feature requests
- [**Code**](https://storybook.js.org/docs/contribute/code.md) for features and bug fixes
- [**Frameworks**](https://storybook.js.org/docs/contribute/framework.md) to get started with a new framework
- [**Documentation**](https://storybook.js.org/docs/contribute/documentation/documentation-updates.md) for documentation improvements, typos, and clarifications
- [**Examples**](https://storybook.js.org/docs/contribute/documentation/new-snippets.md) for new snippets and examples
- [**Addons**](https://storybook.js.org/docs/addons.md) for new addons

## Not sure how to get started?

- [Chat in Discord `#contributing`](https://discord.com/channels/486522875931656193/839297503446695956)
- [Browse "good first issues" to fix](https://github.com/storybookjs/storybook/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
- [Submit a bug report or feature request](https://github.com/storybookjs/storybook/issues)

## AI contributions

### Never let an LLM speak for you

The team welcomes the use of AI as a personal assistant when contributing to Storybook. However, we strongly believe that a real person must be behind every issue and pull request.

All issues and pull requests must be opened by a real person using the official templates. If AI assisted in creating a pull request, please disclose the tool used (e.g. Claude, Codex, Copilot).

Pull requests or issues entirely generated by AI with no human involvement (e.g. by an automated agent) will be labeled by maintainers and closed automatically after 3 days unless a real person responds.

AI-generated comments on issues, pull requests or discussions that add no value or contain incorrect information will be hidden by the maintainers and can be subject to a ban if this becomes a spam behavior.

These measures help reduce maintenance burden and keep the team's work efficient.
> Source: https://storybook.js.org/docs/contribute
---

# RFC process

The RFC (Request for Comment) process is intended to provide a consistent and controlled path for new features to enter the project. It helps ensure that new features are well-designed, well-implemented, and well-tested, and they do not conflict with the project's overall direction and scope.

## Goal

Many changes, such as bug fixes and documentation improvements, can be implemented and reviewed via the normal GitHub pull request workflow. Some changes, however, are considered “substantial”, and we ask that these undergo a design process, solicit community input, and reach a consensus among the Storybook core team.

The purpose of the RFC (Request for Comment) process is to:

- Provide a transparent system for proposing new feature ideas.
- Establish a reliable and well-regulated process for introducing new features into the project.
- Provide a way for the community to participate in developing new features.

### “Feature Request” vs. “RFC”

A _feature request_ is a straightforward and relatively informal way for Storybook users to suggest a new feature or enhancement to the project. While feature requests can provide valuable insights and ideas, they typically do not involve an in-depth design process or require consensus among the core team. Feature requests are usually open to discussion and may or may not be implemented based on factors like popularity, feasibility, and alignment with the project's goals.

On the other hand, an _RFC_ is a more formalized and structured process for proposing substantial changes or additions to the project. It involves following a defined set of steps to ensure that the proposed feature or modification receives proper consideration, design, and feedback. RFCs are typically used for changes that significantly impact the project, such as introducing new API functionality, removing existing features, or establishing new usage conventions. The RFC process aims to foster discussions, gather feedback from a wider audience, and reach consensus among the core team before integrating the proposed change into the project. Accepted RFCs are more likely to be implemented than regular feature requests.

## The RFC lifecycle

### 1. `Status: Proposed`

Open a new GitHub discussion in the [“RFC” category](https://github.com/storybookjs/storybook/discussions/new?category=rfc). Fill out the form as instructed.

_Details matter_: RFCs that do not present convincing motivation, demonstrate a lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly received.

### 2. `Status: In review`

RFCs tend to remain in this stage for a while, giving the community and core team members time to weigh in. During this period, the author of an RFC should be prepared to revise the proposal, integrate feedback, and build consensus. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.

Every week, the Storybook core team conducts a triage meeting to review open RFCs as part of the meeting's agenda. The event is publicly scheduled in the [Storybook Discord](https://discord.gg/storybook) and held in the [Storybook Discord's Watercooler channel](https://discord.com/channels/486522875931656193/486522876388704260). We invite the RFC author(s) and interested members of the community to participate and engage in a more detailed discussion of the RFC. If a core team member deems it necessary, they will be assigned as the "champion" of the RFC. The champion will collaborate with the RFC author and assist them throughout the RFC process.

### 3. `Status: accepted/rejected`

Eventually, the team will decide whether the RFC is a candidate for inclusion in Storybook. On the other hand, an RFC may be rejected by the team after a public discussion has settled and comments have been made summarizing the rationale for rejection.

## Implementing an accepted RFC

The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) is welcome to post an implementation for review after the RFC has been accepted. However, note that the “accepted” status does not indicate priority nor whether it’s being actively worked on.

If you are interested in implementing an "active" RFC, but cannot determine if someone else is already working on it, feel free to ask (e.g., by leaving a comment on the associated issue).

This RFC process took heavy inspiration from the RFC processes from [Rust](https://github.com/rust-lang/rfcs) and [Gatsby](https://www.gatsbyjs.com/contributing/rfc-process/).

**Learn more about contributing to Storybook**

- RFC process for authoring feature requests
- [Code](https://storybook.js.org/docs/contribute/code.md) for features and bug fixes
- [Frameworks](https://storybook.js.org/docs/contribute/framework.md) to get started with a new framework
- [Documentation](https://storybook.js.org/docs/contribute/documentation/documentation-updates.md) for documentation improvements, typos, and clarifications
- [Examples](https://storybook.js.org/docs/contribute/documentation/new-snippets.md) for new snippets
> Source: https://storybook.js.org/docs/contribute/RFC
---

# Code contributions

Contribute a new feature or bug fix to [Storybook's monorepo](https://github.com/storybookjs/storybook). This page outlines how to get your environment set up to contribute code.

## Prerequisites

- Ensure you have Node version 18 installed (suggestion: v18.16.0).
- If you're working with Windows, all commands should be run in a terminal with administrator privileges.

## Initial setup

Start by [forking](https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo) the Storybook monorepo and cloning it locally.

```shell
git clone https://github.com/your-username/storybook.git
cd storybook
```

Storybook uses the [Yarn](https://yarnpkg.com/) package manager. Use [Corepack](https://github.com/nodejs/corepack) to set up the correct version for use with Storybook.

```shell
corepack enable
```

## Run your first sandbox

Storybook development happens in a set of _sandboxes_ which are templated Storybook environments corresponding to different user setups. Within each sandbox, we inject a set of generalized stories that allow us to test core features and addons in all such environments.

To run a sandbox locally, you can use the `start` command:

```shell
yarn start
```

It will install the required prerequisites, build the code, create and link a starter example based on a Vite React setup and finally start the Storybook server.

If all goes well, you should see the sandbox running.

![Storybook sandbox running](../_assets/get-started/example-welcome.png)

## Running a different sandbox template

By default, the `start` command is configured to initialize a Vite-based React template. If you're planning on working on a different renderer instead, you can do so as well. Start by running the `task` command as follows:

```shell
yarn task
```

When prompted, answer the questions as accurately as possible to allow Storybook to determine your goals. After answering these questions, you should see the entire command with the options you've selected should you require to re-run it.

The `yarn task` command takes a few development shortcuts that can catch you off guard when switching branches and may require you to re-run both the `install` and `compile` tasks. You can speed up the process by running the command with the `start-from=install` flag.

## Running tests

After successfully running your [first sandbox](#run-your-first-sandbox), you should have a fully functional Storybook version built on your local machine. Before jumping onto any code changes, verifying everything is working is essential—specifically, the test suite.

Run the following command to execute the tests:

```shell
yarn test
```

## Start developing

Now that you've [verified your setup](#running-tests), it's time to jump into code. The simplest way is to run one of the sandboxes in one terminal window and the interactive build process in a separate terminal.

Assuming you're still running the Vite-based React sandbox initialized after running the `yarn start` command, open a new terminal window and navigate to the `code` directory of the Storybook monorepo. Then, create a new branch for your contribution by running the following command:

```shell
git checkout -b my-first-storybook-contribution
```

Lastly, run the build process with the following:

```shell
yarn build
```

When prompted to start the build process in `watch` mode, answer **yes** to develop in interactive mode. Afterward, choose which packages you want to build. For example, if you're going to work on a feature for `@storybook/addon-docs`, you might want to select both `@storybook/addon-docs` and `storybook`.

Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command **WITHOUT** enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you.

![Storybook package selector](../_assets/contribute/storybook-build-packages-selection-optimized.png)

If the work you'll be doing affects the `Preview` (the innermost Storybook `iframe`, where the stories are displayed), it will automatically refresh one to two seconds after you save.

Otherwise, if it affects the `Manager` (the outermost Storybook `iframe` where the addons are displayed), you'll need to refresh manually after saving.

![Storybook manager preview](../_assets/addons/manager-preview.png)

The `yarn build` command accepts arguments to help speed up your development workflow:

- `--all` will cause all packages to be built
- `--watch` will enable watch mode (and skip the watch mode prompt)
- `--prod` will build for production (and skip the production mode prompt)
- individual package names can be passed, without the `@storybook/` prefix, e.g. `storybook`, `addon-docs`, etc.

For example, to build Storybook and the docs addon in watch mode, run:

```shell
yarn build --watch storybook addon-docs
```

## Check your work

When you're done coding, add documentation and tests as appropriate. That simplifies the PR review process, which means your code will get merged faster.

### Add stories

Adding a story or set of generic stories to our suite helps you test your work.

Assuming you're working on one of the [essential features](https://storybook.js.org/docs/essentials.md), there's a chance that a complete set of stories already exists. Check the addon's `template/stories` directory that documents how it's supposed to work and add your stories there.

If you're modifying something related to a specific renderer (e.g., React, Vue 3, etc.), it will also have a similar `template/stories` directory in which you'll need to add your stories.

### Add tests

Unit tests ensure that Storybook doesn't break accidentally. If your code can regress in non-obvious ways, include unit tests with your pull request. Use the following naming convention:

```
+-- parentFolder
|   +-- [filename].ts
|   +-- [filename].test.ts
```

### End-to-end tests (e2e)

Storybook's monorepo is set up to rely on end-to-end testing with [Playwright](https://playwright.dev) during CI. To help with testing, we encourage running this test suite before submitting your contribution.

To run an e2e test against a sandbox, you can use the `e2e-tests` task:

```shell
yarn task --task e2e-tests --template=react-vite/default-ts --start-from=auto
```

If there are issues and you'd like to debug them, you can pass a `DEBUG=1` environment variable, and Playwright will run in watch mode.

```shell
DEBUG=1 yarn task --task e2e-tests --template=react-vite/default-ts --start-from=auto
```

## Submit a pull request

Before submitting your contribution, run the test suite one last time with the following:

```shell
yarn test
```

Storybook relies on [Vitest](https://vitest.dev/) as part of its testing suite. During the test run, if you spot that snapshot tests are failing, re-run the command with the `-u` flag to update them.

Doing this prevents last-minute bugs and is a great way to merge your contribution faster once you submit your pull request. Failing to do so will lead to one of the maintainers marking the pull request with the **Work in Progress** label until all tests pass.

### Target `next` branch

Once the test suite finishes, it's time to commit, push and open a pull request against Storybook's `next` (default) branch. This branch is where all active development happens and is associated with the latest prerelease version (e.g., `7.0.0-alpha.47`).

If your contribution focuses on a bugfix and you want it featured in the next stable release, mention it in the pull request description. We'll try to patch it if it appears non-disruptive and fixes a critical bug.

#### Useful resources when working with forks

- [Sync a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork)
- [Merge an upstream repository into your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork)

### Reproducing job failures

After creating your PR, if one of the CI jobs failed, when checking the logs of that job, you will see that it printed a message explaining how to reproduce the task locally. Typically that involves running the task against the right template:

```shell
yarn task --task e2e-tests --template=react-vite/default-ts --start-from=install
```

Typically it is a good idea to start from the `install` task to ensure your local code is completely up to date. If you reproduce the failure, you can try and make fixes, [compile them](#start-developing) with `build`, then rerun the task with `--start-from=auto`.

The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently.

If you are having trouble reproducing, try rerunning the command with the `--no-link` flag. If you need to do that, you'll need to run it with `--start-from=compile` after each code change.

## How to work with reproductions

We encourage bug reports to include reproductions. In the same way that it's possible to [develop interactively](#start-developing) against example projects in the monorepo, it's also possible to develop against a reproduction repository.

To do so, run the following command in the root of the monorepo:

```shell
npx storybook@next link https://github.com/your-username/your-project.git
```

This command creates a project `../storybook-repros/your-project`, and automatically links it to your local Storybook code. After connecting it, you should be able to run Storybook and develop as mentioned [above](#start-developing).

If you already have a reproduction on your local machine, you can similarly link it to your monorepo dev setup with the `--local` flag:

```shell
npx storybook@next link --local /path/to/local-repro-directory
```

The `storybook link` command relies on [Yarn linking](https://yarnpkg.com/cli/link/) under the hood. It requires your local reproduction to be using [Yarn 2 or higher](https://yarnpkg.com/) as well, which is the case if you've already enabled it with the [`storybook sandbox`](https://storybook.js.org/docs/contribute/how-to-reproduce.md) command per our contribution guidelines. The process will fail if you're trying to link a non-Yarn 2 project.

## Developing a template

The first step is to add an entry to `code/lib/cli-storybook/src/sandbox-templates.ts`, which is the master list of all repro templates:

```ts
'cra/default-js': {
    name: 'Create React App (Javascript)',
    script: 'npx create-react-app .',
    inDevelopment: true,
    expected: {
      framework: '@storybook/cra',
      renderer: '@storybook/react',
      builder: '@storybook/builder-webpack5',
    },
  },
```

Add the `inDevelopment` flag until the PR is merged (you can fast-follow it with a second PR to remove the flag), as it'll make the development process much easier.

The **`key`** `cra/default-js` consists of two parts:

- The prefix is the tool that was used to generate the repro app
- The suffix is options that modify the default install, e.g. a specific version or options

The **`script`** field is what generates the application environment. The `.` argument is “the current working directory” which is auto-generated based on the key (e.g. `repros/cra/default-js/before-storybook`). The `{{beforeDir}}` key can also be used, which will be replaced by the path of that directory.

The rest of the fields are self-explanatory:

The **`skipTasks`** field exists because some sandboxes might not work properly in specific tasks temporarily, but we might still want to run the other tasks. For instance, a bug was introduced outside of our control, which fails only in the `test-runner` task.

The **`name`** field should contain a human readable name/description of the template.

The **`expected`** field reflects what framework/renderer/builder we expect `sb init` to generate. This is useful for assertions while generating sandboxes. If the template is generated with a different expected framework, for instance, it will fail, serving as a way to detect regressions.

### Running a sandbox

If your template has a `inDevelopment` flag, it will be generated (locally) as part of the sandbox process. You can create the sandbox with the following command, where `<template-key>` is replaced by the id of the selected template e.g. `cra/default-js`:

```bash
yarn task --task dev --template <template-key> --start-from=install
```

Templates with `inDevelopment` will automatically run with `--no-link` flag as it is required for the local template generation to work.

Once the PR is merged, the template will be generated on a nightly cadence and you can remove the `inDevelopment` flag and the sandbox will pull the code from our templates repository.

## Troubleshooting

<details>
<summary><code>yarn build --all --watch</code> watches everything but is resource-intensive</summary>

It's troublesome to know which packages you'll change ahead of time, and watching them can be highly demanding, even on modern machines. If you're working on a powerful enough machine, you can use `yarn build --all --watch` instead of `yarn build`.

</details>

**Learn more about contributing to Storybook**

- [RFC process](https://storybook.js.org/docs/contribute/RFC.md) for authoring feature requests
- Code for features and bug fixes
- [Frameworks](https://storybook.js.org/docs/contribute/framework.md) to get started with a new framework
- [Documentation](https://storybook.js.org/docs/contribute/documentation/documentation-updates.md) for documentation improvements, typos, and clarifications
- [Examples](https://storybook.js.org/docs/contribute/documentation/new-snippets.md) for new snippets
> Source: https://storybook.js.org/docs/contribute/code
---

# Documentation updates

Fix a typo or clarify a section of the docs. This page outlines how to edit the documentation.

## Find the Markdown file

Scroll to the bottom of the document in question, then click ✍️ Edit on GitHub – PRs welcome! This will open the Markdown file on GitHub.

![Storybook documentation edit](../../_assets/contribute/storybook-edit-docs-optimized.png)

Use GitHub's web editor by clicking the pencil icon on the right-hand corner. Tweak the document to your liking.

![GitHub edit documentation](../../_assets/contribute/github-docs-edit-optimized.png)

Scroll down to the bottom of the document page on GitHub and describe what you changed and why. Select the `Create a new branch for this commit and start a pull request` option then click the `Propose changes` button.

![Fill the commit information](../../_assets/contribute/storybook-docs-submit-changes-optimized.png)

## Create the pull request

In the Storybook repository, create a pull request that describes changes and includes additional context that would help maintainers review. Once you submit the PR, a maintainer will guide you through the triage and merge process.

**Learn more about contributing to Storybook**

- [RFC process](https://storybook.js.org/docs/contribute/RFC.md) for authoring feature requests
- [Code](https://storybook.js.org/docs/contribute/code.md) for features and bug fixes
- [Frameworks](https://storybook.js.org/docs/contribute/framework.md) to get started with a new framework
- Documentation for documentation improvements, typos, and clarifications
- [Examples](https://storybook.js.org/docs/contribute/documentation/new-snippets.md) for new snippets
> Source: https://storybook.js.org/docs/contribute/documentation/documentation-updates
---

# Code snippets contributions

Add or update the code snippets in the documentation. This page outlines how the code snippets are structured.

## Documented frameworks

Storybook maintains code snippets for a [variety of frameworks](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md). We try to keep them up to date as framework APIs evolve. But keeping track of every API change in every framework is tricky.

We welcome community contributions to the code snippets. Here's a matrix of the frameworks for which we have snippets. Help us add snippets for your favorite framework.

| React | Vue 3 | Angular | Web Components | Svelte | Solid | Ember | HTML | Preact | Qwik |
| ----- | ----- | ------- | -------------- | ------ | ----- | ----- | ---- | ------ | ---- |
| ✅    | ✅    | ✅      | ✅             | ✅     | ✅    | ❌    | ❌   | ❌     | ❌   |

## Snippet syntax

The code snippets referenced throughout the Storybook documentation are located in the [`docs/_snippets`](https://github.com/storybookjs/storybook/tree/next/docs/_snippets) directory inside individual Markdown files, containing the [supported frameworks](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md), features and languages (i.e., JavaScript, MDX, TypeScript).

### Example

The following code block demonstrates how to structure a code snippet in the Storybook documentation and the attributes you can use to provide additional context to the code snippet.

````md title="docs/_snippets/button-group-story.md"
```ts filename="ButtonGroup.stories.ts" renderer="vue" language="ts" tabTitle="3"

//👇 Imports the Button stories

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

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

export const Pair: Story = {
  render: (args) => ({
    components: { ButtonGroup },
    setup() {
      return { args };
    },
    template: '',
  }),
  args: {
    buttons: [{ ...ButtonStories.Primary.args }, { ...ButtonStories.Secondary.args }],
    orientation: 'horizontal',
  },
};
```
````

## Common attributes for code snippets

Following are the attributes you'll use most often in the Storybook documentation code snippets, as well as a brief explanation of each to help you understand the context in which they are used.

### File name as title

Most code examples should include a file name so readers can understand which file they relate to and where to paste it into their project. For code examples, include the `filename` attribute wrapped with quotation marks to indicate the file name. This is not required if the example relates to a terminal command.

````md title="docs/_snippets/button-stories.md"
```ts filename="Button.stories.ts"

```
````

### Language configuration

Use the `language` attribute to define the language to which the code snippet applies. The documentation uses this attribute to determine which variant to display (e.g., JavaScript, TypeScript, MDX).

````md title="docs/_snippets/button-stories.md"
```ts filename="Button.stories.ts" language="js|ts|mdx"

```
````

### Framework-specific code

Use the `renderer` attribute to indicate which of the [supported frameworks](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md) the code snippet belongs to.

````md title="docs/_snippets/button-stories.md"
```ts filename="Button.stories.ts" language="ts" renderer="react|vue|angular|web-components|ember|html|svelte|preact|qwik|solid"

```
````

Alternatively, if you're documenting examples that apply to multiple frameworks, use the `renderer` attribute with the `common` value to indicate that the code snippet is framework-agnostic.

````md title="docs/_snippets/button-stories.md"
```ts filename="Button.stories.ts" language="ts" renderer="common"

```
````

### Package manager configuration

Use the `packageManager` attribute to configure the package manager used in the example from the following options: `npm`, `yarn`, or `pnpm`.

````md title="docs/_snippets/storybook-run-dev.md"
```shell renderer="common" packageManager="npm|yarn|pnpm"

```
````

### Working with multiple snippets

Use the `tabTitle` attribute to indicate the tab title in which the code snippet will be displayed. This attribute should only be used when multiple examples are in a single code snippet file.

````md title="docs/_snippets/component-decorator.md"
```ts filename="YourComponent.stories.ts" language="ts" renderer="common" tabTitle="Story"

```

```ts filename=".storybook/preview.ts|tsx" language="ts" renderer="common" tabTitle="Storybook configuration"

```
````

## Contributing code snippets

You can start contributing to the Storybook documentation by now that you're familiar with how the documentation is organized, the code snippet's structure, and available options. Assuming that you have already set up your [local development environment](https://storybook.js.org/docs/contribute/code.md#initial-setup) and are ready to contribute, the following steps will guide you through contributing code snippets to the Storybook documentation.

Start by creating a new branch on your local Storybook monorepo with the following command:

```shell
git checkout -b code-snippets-for-framework
```

Browse the documentation and look for the code snippets you want to contribute. For example, on the [setup page](https://github.com/storybookjs/storybook/blob/next/docs/get-started/setup.mdx) you should see the following:

```mdx title="docs/get-started/setup.mdx"
```ts
// YourComponent.stories.ts|tsx — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.

//👇 This default export determines where your story goes in the story list
const meta = {
  component: YourComponent,
} satisfies Meta<typeof YourComponent>;

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

export const Basic: Story = {
  args: {
    //👇 The args you need here will depend on your component
  },
};
```

```ts
// YourComponent.stories.ts|tsx — CSF Next 🧪

//👇 This default export determines where your story goes in the story list
const meta = preview.meta({
  component: YourComponent,
});

export const Basic = meta.story({
  args: {
    //👇 The args you need here will depend on your component
  },
});
```
```

Open the file inside the `docs/_snippets` directory and adjust the content to match the code snippet you're willing to contribute. For example:

````md title="docs/_snippets/your-component.md"
```ts filename="YourComponent.stories.ts" renderer="qwik" language="ts"

//👇 This default export determines where your story goes in the story list
const meta = {
  component: YourComponent,
} satisfies Meta<YourComponentProps>;

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

export const FirstStory: Story = {
  args: {
    //👇 The args you need here will depend on your component
  },
};
```
````

Go through the rest of the documentation and repeat the process.

## Preview your work

Before submitting your contribution, we encourage you to check your work against the Storybook website. Doing this prevents last-minute issues with the documentation and is also an excellent way for the maintainers to merge faster once you submit the pull request. However, failing to do so will lead one of the maintainers to notify you that your contribution has an issue.

Start by forking the Storybook [website repository](https://github.com/storybookjs/web) and cloning it locally.

```shell
git clone https://github.com/your-username/web.git
```

Navigate to the `web` directory and install the required dependencies.

```shell
npm install
```

We recommend that you generate a website build first to ensure you can preview your changes locally and verify that everything is working as expected. To do so, run the following command:

```shell
npm run build:frontpage
```

When executed, this command will retrieve the required files needed to successfully build the Storybook website, including current documentation versions (e.g., `6.5`, `7.6`, `8.x`), and copy them to the `apps/frontpage/docs/` directory, organized by version number.

Run the `sync-docs` command to connect the documentation from the Storybook monorepo to the Storybook website. When prompted, provide the path to your local fork of the Storybook monorepo and the documentation version you're working on.

```shell
npm run sync-docs
```

Finally, open a new terminal window and run the `dev` command to start the Storybook website.

```shell
npm run dev
```

If all goes well, you should see the Storybook website running. Open a browser window to `http://localhost:3000`, click the Docs link to open the documentation, and select your framework from the dropdown.

Go through the documentation and check your work.

## Submit your contribution

Once you have verified that your changes are working as expected, you're ready to create a "Pull Request". This will let the Storybook maintainers know you have some changes to propose. At this point, we can give you feedback and request changes. To help with the review process, we encourage you to add a clear title and description of your work.

## Troubleshooting

### Code snippets not displaying

If you're documenting an example that includes the `packageManager` attribute combined with another example, the documentation might not display the code snippets correctly. To avoid this, you can divide the examples into separate files and reference them in the documentation.

## Learn more about contributing to Storybook

- [RFC process](https://storybook.js.org/docs/contribute/RFC.md) for authoring feature requests
- [Code](https://storybook.js.org/docs/contribute/code.md) for features and bug fixes
- [Frameworks](https://storybook.js.org/docs/contribute/framework.md) to get started with a new framework
- [Documentation](https://storybook.js.org/docs/contribute/documentation/documentation-updates.md) for documentation improvements, typos, and clarifications
- Examples for new snippets
> Source: https://storybook.js.org/docs/contribute/documentation/new-snippets
---

# Contributing a Storybook framework

A Storybook framework is a node package that enables out-of-the-box support for either a metaframework (Next.js, NuxtJS, SvelteKit) or a combination of [builder](https://storybook.js.org/docs/builders.md) (Webpack, Vite) plus renderer (React, Angular, Vue 3, web components, etc).

For metaframeworks, the Storybook framework also takes care of additional configuration necessary to make Storybook behave similarly to apps generated by the metaframework. For example, `@storybook/nextjs` [recreates or mocks a number of features of Next.js apps](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/README.md#supported-features) inside Storybook.

For your reference, you can view [all of the official Storybook frameworks](https://github.com/storybookjs/storybook/tree/next/code/frameworks), including their full source code and documentation.

## How to make a framework

### 1. Decide on a package name

The name should start with `storybook-framework-` and then correspond to what your framework supports. For example, a framework targeting SvelteKit would be `storybook-framework-svelte-kit` and a framework targeting Stencil with Vite would be `storybook-framework-stencil-vite`. When not targeting a metaframework, the naming convention is `storybook-framework-<renderer>-<builder>`.

### 2. Consider what your framework will need to do

The goal is to make Storybook behave—out-of-the-box—as similarly as possible to the metaframework or builder-renderer combination you’re targeting.

For metaframeworks, this means attempting to recreate any builder or babel configuration provided by the metaframework. You should try to do so in a way that respects the user's existing project configuration as much as possible.

The library or libraries your framework supports may have different major versions available. Consider which versions of each library your framework will support. You will need to account for the changes within those different versions or split your framework into different versions/packages itself to support each library version. To speed up maintenance, please consider adding integration tests for the various library versions your framework supports.

### 3. Write the documentation

Before writing any code, write a helpful README that contains installation instructions and a list of available features. Use the [README for `@storybook/nextjs`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/README.md) as a template. Writing the documentation first helps guide your other work.

### 4. Author the framework itself

A framework can contain the following parts:

#### `package.json` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/package.json))

Because a framework is a node package, it must contain a `package.json` file. Here’s a template you can use to start:

<details>
<summary><code>package.json</code> template</summary>

```json title="package.json"
{
  "name": "<your-framework-name>",
  "version": "1.0.0",
  "description": "Storybook for <meta-framework-name> or <renderer> & <builder>",
  "keywords": [
    "Storybook",
    "<meta-framework-name>",
    "<renderer>",
    "<builder>",
    "<anything>",
    "<else>",
    "<relevant>"
  ],
  "homepage": "<your package's homepage>",
  "bugs": {
    "url": "https://github.com/<your-org>/<your-repo>/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/<your-org>/<your-repo>.git",
    "directory": "<path/to/your/framework>"
  },
  "license": "MIT",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "require": "./dist/index.js",
      "import": "./dist/index.mjs"
    },
    "./preset": {
      "types": "./dist/preset.d.ts",
      "require": "./dist/preset.js",
      "import": "./dist/preset.mjs"
    },
    "./preview.js": {
      "types": "./dist/preview.d.ts",
      "require": "./dist/preview.js",
      "import": "./dist/preview.mjs"
    },
    "./package.json": "./package.json"
  },
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "files": ["dist/**/*", "types/**/*", "README.md", "*.js", "*.d.ts"],
  "scripts": {
    "check": "tsc --noEmit",
    "test": "..."
  },
  "dependencies": {
    "storybook": "^9.0.0",
    "@storybook/<builder>": "^9.0.0",
    "@storybook/<renderer>": "^9.0.0"
  },
  "devDependencies": {
    "typescript": "x.x.x",
    "<meta-framework>": "^x.x.x",
    "<builder>": "^x.x.x"
  },
  "peerDependencies": {
    "<meta-framework>": "^x.x.x || ^x.x.x",
    "<renderer>": "^x.x.x || ^x.x.x",
    "<builder>": "^x.x.x"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "publishConfig": {
    "access": "public"
  }
}
```

A few notes on some of those properties:

- `exports`: The root, `./preset`, and `package.json` exports are required. If your framework has a `preview.js`, then that is required as well.
- `types`: We strongly encourage you to author your framework in TypeScript and distribute the types.
- `dependencies` and `devDependencies`: These are just examples. Yours may look quite different.
- `peerDependencies`: If your framework provides support for multiple versions of the libraries you’re targeting, be sure that is represented here.

</details>

#### `preset.js` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts))

The [preset API](https://storybook.js.org/docs/addons/writing-presets.md) is where you will configure the Storybook core (which builder and renderer are used by your framework), the builder (via either the [`webpackFinal`](https://storybook.js.org/docs/builders/webpack.md#override-the-default-configuration) or [`viteFinal`](https://storybook.js.org/docs/builders/vite.md#configuration) export), babel (via the `babel` export), any necessary addons, and any available options for your framework.

#### `preview.js` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preview.tsx))

The (optional) [preview API](https://storybook.js.org/docs/configure/index.md#configure-story-rendering) is where you configure the rendering of stories, such as global decorators or initializing some runtime config needed for your framework to behave as expected. If your framework requires this file, note that you also need to [configure the `previewAnnotations` in `preset.js`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts#L71-L74).

#### `types.ts` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/types.ts))

If you author your framework in TypeScript (recommended), you should export the type for `StorybookConfig` which reflects the available options of your framework.

### 5. Test your framework

Test it in a fresh project using a Storybook set up as close as possible to your framework. For example, for `@storybook/nextjs`, which uses React and Webpack5, start with a project that uses `@storybook/react` and `@storybook/builder-webpack5`. Follow the installation instructions from your README and ensure everything works as expected. Remember to test the various versions, configs, and options for the libraries you’re supporting.

### 6. Let us know!

Once it's fully tested and released, please let us know about your framework by either announcing it in the [`#showcase`](https://discord.com/channels/486522875931656193/1048740936953376859) Discord channel or tweeting it and mentioning `@storybookjs`. It's our hope that well-made community frameworks can eventually move into the Storybook codebase and be considered "officially" supported.

**Learn more about contributing to Storybook**

- [RFC process](https://storybook.js.org/docs/contribute/RFC.md) for authoring feature requests
- [Code](https://storybook.js.org/docs/contribute/code.md) for features and bug fixes
- Frameworks to get started with a new framework
- [Documentation](https://storybook.js.org/docs/contribute/documentation/documentation-updates.md) for documentation improvements, typos, and clarifications
- [Examples](https://storybook.js.org/docs/contribute/documentation/new-snippets.md) for new snippets
> Source: https://storybook.js.org/docs/contribute/framework
---

# Create a reproduction

A reproducible test case lets you isolate the cause of a problem, which is the first step towards fixing it! This page outlines how to get set up to create a reproduction.

## Why should you create a reproduction?

A reproducible test case is a great way to share a specific set of conditions that causes a bug. It allows both the maintainers and the community to verify, narrow down the cause of the problem and help you fix the issue.

## Pre-requisites

Make sure you have:

- Installed [`Yarn`](https://yarnpkg.com/) on your local development machine.
- A [GitHub account](https://github.com/signup) for hosting the reproduction's code.
- A [Chromatic account](https://www.chromatic.com/start/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) for publishing your Storybook.

## Initial setup

First, open a terminal and run the following command:

```shell
npx storybook@next sandbox
```

You can append a template name in the command to get filtered results (e.g., `npx storybook@next sandbox react`).

Next, choose the template you want to work with:

![Storybook reproduction generator template](../_assets/contribute/storybook-reproduction-generator-template.png)

Finally, enter a location for your reproduction:

![Storybook reproduction location](../_assets/contribute/storybook-reproduction-generator-location.png)

If you don't provide a full path for the reproduction it will be generated in the current directory.

If everything worked as it should, you should have a fully functional Storybook set up in your local environment.

## Third-party dependencies & addons

Before adding code, install and configure any necessary packages. For example, if you run into a problem with a CSS framework (e.g., [Tailwind](https://tailwindcss.com/)), you should install and configure it.

Install and configure any Storybook [addons](https://storybook.js.org/addons/) that relate to the issue (e.g.,`@storybook/addon-a11y`).

## Add stories

Any Storybook reproduction wouldn't be complete without [stories](https://storybook.js.org/docs/writing-stories.md). To help fix your issue faster, we encourage you to include the minimum amount of stories that will replicate your issue.

## Host

When you've finished your work, you'll need to host your reproduction. Start by signing into GitHub.com and create a [new repository](https://github.com/new).

![github repository for reproductions](../_assets/contribute/github-new-repository-reproduction-optimized.png)

Then, follow GitHub's instructions to set up the repository.

![github repository instructions](../_assets/contribute/github-repository-steps-optimized.png)

Don't forget to replace `your-username` with your own account name.

## Publish

An excellent way to check your reproduction is to have it deployed online. We recommend [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook), a free publishing service created by the Storybook maintainers. It allows you to deploy and host your reproduction safely and securely in the cloud.

### Helpful resources when working with Chromatic

- [Publish Storybook](https://storybook.js.org/docs/sharing/publish-storybook.md)
- [Setup Chromatic](https://www.chromatic.com/docs/setup?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook)
- [Automate Chromatic with continuous integration](https://www.chromatic.com/docs/ci?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook)

## Submit the issue

Finally, create your issue in the [Storybook issue tracker](https://github.com/storybookjs/storybook/issues/new/choose), go through the required steps, and provide a detailed description of the problem. Add the GitHub repository and [deployed reproduction](https://www.chromatic.com/docs/setup?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook#view-published-storybook) to help with the triage process.
> Source: https://storybook.js.org/docs/contribute/how-to-reproduce
---

# Frequently Asked Questions

Here are some answers to frequently asked questions. If you have a question, you can ask it in our [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help).

## Error: No angular.json file found

Storybook can be set up for both single-project and multi-project Angular workspaces. To set up Storybook for a project, run [the install command](https://storybook.js.org/docs/get-started/install.md) at the root of the workspace where the `angular.json` file is located. During initialization, the `.storybook` folder will be created and the `angular.json` file will be edited to add the Storybook configuration for the selected project. It's important to run the command at the root level to ensure that Storybook detects all projects correctly.

## How can I opt-out of Angular Ivy?

In case you are having trouble with Angular Ivy you can deactivate it in your `main.js|ts`:

## How can I opt-out of Angular ngcc?

In case you postinstall ngcc, you can disable it:

Please report any issues related to Ivy in our [GitHub Issue Tracker](https://github.com/storybookjs/storybook/labels/app%3A%20angular) as the support for View Engine will be dropped in a future release of Angular.

## How can I run coverage tests with Create React App and leave out stories?

Create React App does not allow providing options to Jest in your `package.json`, however you can run `jest` with commandline arguments:

```sh
npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stories/*"]'
```

If you're using [`Yarn`](https://yarnpkg.com/) as a package manager, you'll need to adjust the command accordingly.

## How do I setup Storybook to share Webpack configuration with Next.js?

Storybook's [Next.js framework](https://storybook.js.org/docs/get-started/frameworks/nextjs.md) will read from your `next.config.js` file by default. If your configuration file is named or located differently, you can specify the path in your Storybook main configuration file:

```ts
// .storybook/main.ts — CSF 3

// Replace your-framework with nextjs or nextjs-vite

const config: StorybookConfig = {
  // ...
  framework: {
    name: '@storybook/your-framework',
    options: {
      nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with nextjs or nextjs-vite

export default defineMain({
  // ...
  framework: {
    name: '@storybook/your-framework',
    options: {
      nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
    },
  },
});
```

## How do I fix module resolution in special environments?

In case you are using [Yarn Plug-n-Play](https://yarnpkg.com/features/pnp) or your project is set up within a mono repository environment, you might run into issues with module resolution similar to this when running Storybook:

```shell
WARN   Failed to load preset: "@storybook/react-webpack5/preset"
Required package: @storybook/react-webpack5 (via "@storybook/react-webpack5/preset")
```

To fix this, you can wrap the package name inside your Storybook configuration file (i.e., `.storybook/main.js|ts`) as follows:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.

const getAbsolutePath = (packageName: string) =>
  dirname(fileURLToPath(import.meta.resolve(`${packageName}/package.json`)));

const config: StorybookConfig = {
  framework: {
    // Replace your-framework with the same one you've imported above.
    name: getAbsolutePath('@storybook/your-framework'),
    options: {},
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    //👇 Use getAbsolutePath when referencing Storybook's addons and frameworks
    getAbsolutePath('@storybook/addon-docs'),
  ],
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)

const getAbsolutePath = (packageName: string) =>
  dirname(fileURLToPath(import.meta.resolve(join(packageName, 'package.json'))));

export default defineMain({
  framework: {
    // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
    name: getAbsolutePath('@storybook/your-framework'),
    options: {},
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    //👇 Use getAbsolutePath when referencing Storybook's addons and frameworks
    getAbsolutePath('@storybook/addon-docs'),
  ],
});
```

## Extensionless imports in Storybook main config

When upgrading or running Storybook, you may see warnings about extensionless relative imports in `.storybook/main.<js|ts>` (for example: `import sharedMain from '../main'`).
Storybook requires explicit extensions in config imports to avoid this deprecation warning.

To fix the issue, just make sure to include the extension of the file (TypeScript or Javascript) you're importing:

```ts title=".storybook/main.<js|ts>"
// Change from this 👇

// To this 👇

```

### For TypeScript users (`.storybook/main.ts`)

You will also need to configure TypeScript so these imports type-check without emitting JavaScript:

```json title=".storybook/tsconfig.json"
{
  "extends": "<path-to-your-main-tsconfig>",
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}
```

It is advisable to add a `.storybook/tsconfig.json` file so that you apply changes only to Storybook config files, and not your entire project.

## How do I setup the new React Context Root API with Storybook?

If your installed React Version equals or is higher than 18.0.0, the new React Root API is automatically used and the newest React [concurrent features](https://reactjs.org/docs/concurrent-mode-intro.html) can be used.

You can opt-out from the new React Root API by setting the following property in your `.storybook/main.js|ts` file:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using (e.g., nextjs, react-webpack5)

const config: StorybookConfig = {
  framework: {
    name: '@storybook/your-framework',
    options: {
      legacyRootApi: true,
    },
  },
};

export default config;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using (e.g., nextjs, react-webpack5)

const config = defineMain({
  framework: {
    name: '@storybook/your-framework',
    options: {
      legacyRootApi: true,
    },
  },
});

export default config;
```

## Why is there no addons channel?

A common error is that an addon tries to access the "channel", but the channel is not set. It can happen in a few different cases:

1. You're trying to access addon channel (e.g., by calling `setOptions`) in a non-browser environment like Jest. You may need to add a channel mock:

   ```js
   import { addons, mockChannel } from 'storybook/preview-api';

   addons.setChannel(mockChannel());
   ```

2. In React Native, it's a special case documented in [#1192](https://github.com/storybookjs/storybook/issues/1192)

## Why aren't the addons working in a composed Storybook?

Composition is a new feature that we released with version 6.0, and there are still some limitations to it.

For now, the addons you're using in a composed Storybook will not work.

We're working on overcoming this limitation, and soon you'll be able to use them as if you are working with a non-composed Storybook.

## Can I have a Storybook with no local stories?

Storybook does not work unless you have at least one local story (or docs page) defined in your project. In this context, local means a `.stories.*` or `.mdx` file that is referenced in your project's `.storybook/main.js` config.

If you're in a [Storybook composition](https://storybook.js.org/docs/sharing/storybook-composition.md) scenario, where you have multiple Storybooks, and want to have an extra Storybook with no stories of its own, that serves as a "glue" for all the other Storybooks in a project for demo/documentation purposes, you can do the following steps:

Introduce a single `.mdx` docs page (addon-docs required), that serves as an Introduction page, like so:

```mdx title="Introduction.mdx"
# Welcome

Some description here
```

And then refer to it in your Storybook config file:

```ts
// .storybook/main.ts — CSF 3
// Replace your-framework with the framework you are using, e.g., nextjs-vite, vue3-vite, angular, sveltekit, etc.

const preview: Preview = {
  // ...
  // define at least one local story/page here
  stories: ['../Introduction.mdx'],
  // define composed Storybooks here
  refs: {
    firstProject: { title: 'First', url: 'some-url' },
    secondProject: { title: 'Second', url: 'other-url' },
  },
};

export default preview;
```

```ts
// .storybook/main.ts — CSF Next 🧪
// Replace your-framework with the framework you are using, e.g., nextjs, nextjs-vite, react-vite, etc.

const config = defineMain({
  // ...
  // define at least one local story/page here
  stories: ['../Introduction.mdx'],
  // define composed Storybooks here
  refs: {
    firstProject: { title: 'First', url: 'some-url' },
    secondProject: { title: 'Second', url: 'other-url' },
  },
});

export default config;
```

## Which community addons are compatible with the latest version of Storybook?

Starting with Storybook version 6.0, we've introduced some great features aimed at streamlining your development workflow.

With this, we would like to point out that if you plan on using addons created by our fantastic community, you need to consider that some of those addons might be working with an outdated version of Storybook.

We're actively working to provide a better way to address this situation, but in the meantime, we'd like to ask for a bit of caution on your end so that you don't run into unexpected problems. Let us know by leaving a comment in the following [GitHub issue](https://github.com/storybookjs/storybook/issues/26031) so that we can gather information and expand the current list of addons that need to be updated to work with the latest version of Storybook.

## Is it possible to browse the documentation for past versions of Storybook?

With the release of version 6.0, we updated our documentation as well. That doesn't mean that the old documentation was removed. We kept it to help you with your Storybook migration process. Use the content from the table below in conjunction with our [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md).

We're only covering versions 5.3 and 5.0 as they were important milestones for Storybook. If you want to go back in time a little more, you'll have to check the specific release in the monorepo.

| Section       | Page                                            | Current Location                                                                          | Version 5.3 location                                                                                                                                                                                                                                                 | Version 5.0 location                                                                                                                                     |
| ------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| N/A           | Why Storybook                                   | [See current documentation](https://storybook.js.org/docs/get-started/why-storybook.md)                              | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
| Get started   | Install                                         | [See current documentation](https://storybook.js.org/docs/get-started/install.md)                                    | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides/quick-start-guide)                                                                                                                                     | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/guides/quick-start-guide)                         |
|               | What's a story                                  | [See current documentation](https://storybook.js.org/docs/get-started/whats-a-story.md)                              | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides)                                                                                                                                    | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/guides)                        |
|               | Browse Stories                                  | [See current documentation](https://storybook.js.org/docs/get-started/browse-stories.md)                             | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides)                                                                                                                                    | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/blob/release/5.0/docs/src/pages/guides)                        |
|               | Setup                                           | [See current documentation](https://storybook.js.org/docs/get-started/setup.md)                                      | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides)                                                                                                                                    | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/guides)                        |
| Write stories | Introduction                                    | [See current documentation](https://storybook.js.org/docs/writing-stories.md)                                  | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/writing-stories)                                                                                                                                       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/basics/writing-stories)                           |
|               | Parameters                                      | [See current documentation](https://storybook.js.org/docs/writing-stories/parameters.md)                             | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/writing-stories/index.md#parameters)                                                                                                                   | Non existing feature or undocumented                                                                                                                     |
|               | Decorators                                      | [See current documentation](https://storybook.js.org/docs/writing-stories/decorators.md)                             | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/writing-stories/index.md#decorators)                                                                                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/basics/writing-stories/index.md#using-decorators) |
|               | Naming components and hierarchy                 | [See current documentation](https://storybook.js.org/docs/writing-stories/naming-components-and-hierarchy.md)        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/writing-stories)                                                                                                                                       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/basics/writing-stories)                           |
|               | Build pages and screens                         | [See current documentation](https://storybook.js.org/docs/writing-stories/build-pages-with-storybook.md)             | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Stories for multiple components                 | [See current documentation](https://storybook.js.org/docs/writing-stories/stories-for-multiple-components.md)        | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
| Write docs    | Autodocs                                        | [See current documentation](https://storybook.js.org/docs/writing-docs/autodocs.md)                                  | See versioned addon documentation                                                                                                                                                                                                                                    | Non existing feature or undocumented                                                                                                                     |
|               | MDX                                             | [See current documentation](https://storybook.js.org/docs/writing-docs/mdx.md)                                       | See versioned addon documentation                                                                                                                                                                                                                                    | Non existing feature or undocumented                                                                                                                     |
|               | Doc Blocks                                      | [See current documentation](https://storybook.js.org/docs/writing-docs/doc-blocks.md)                                | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Preview and build docs                          | [See current documentation](https://storybook.js.org/docs/writing-docs/build-documentation.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
| Testing       | Visual tests                                    | [See current documentation](https://storybook.js.org/docs/writing-tests/visual-testing.md)                           | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/testing/automated-visual-testing)                                                                                                                             | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/testing/automated-visual-testing)                 |
|               | Accessibility tests                             | [See current documentation](https://storybook.js.org/docs/writing-tests/accessibility-testing.md)                    | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Interaction tests                               | [See current documentation](https://storybook.js.org/docs/writing-tests/interaction-testing.md)                      | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/testing/interaction-testing)                                                                                                                                  | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/testing/interaction-testing)                      |
|               | Snapshot tests                                  | [See current documentation](https://storybook.js.org/docs/writing-tests/snapshot-testing.md)                         | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/testing/structural-testing)                                                                                                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/testing/structural-testing)                       |
|               | Import stories in tests/Unit tests              | [See current documentation](https://storybook.js.org/docs/writing-tests/integrations/stories-in-unit-tests.md)       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/testing/react-ui-testing)                                                                                                                                     | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/testing/react-ui-testing)                         |
|               | Import stories in tests/End-to-end testing      | [See current documentation](https://storybook.js.org/docs/writing-tests/integrations/stories-in-end-to-end-tests.md) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/testing/react-ui-testing)                                                                                                                                     | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/testing/react-ui-testing)                         |
| Sharing       | Publish Storybook                               | [See current documentation](https://storybook.js.org/docs/sharing/publish-storybook.md)                              | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/exporting-storybook)                                                                                                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/basics/exporting-storybook)                       |
|               | Embed                                           | [See current documentation](https://storybook.js.org/docs/sharing/embed.md)                                          | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Composition                                     | [See current documentation](https://storybook.js.org/docs/sharing/storybook-composition.md)                          | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Package Composition                             | [See current documentation](https://storybook.js.org/docs/sharing/package-composition.md)                            | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
| Essentials    | Controls                                        | [See current documentation](https://storybook.js.org/docs/essentials/controls.md)                                    | Controls are specific to version 6.0 see [Knobs versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/addons/knobs)                                                                                                                     | Controls are specific to version 6.0 see [Knobs versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/addons/knobs)         |
|               | Actions                                         | [See current documentation](https://storybook.js.org/docs/essentials/actions.md)                                     | [See addon versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/addons/actions)                                                                                                                                                        | [See addon versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/addons/actions)                                            |
|               | Viewport                                        | [See current documentation](https://storybook.js.org/docs/essentials/viewport.md)                                    | [See addon versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/addons/viewport)                                                                                                                                                       | [See addon versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/addons/viewport)                                           |
|               | Backgrounds                                     | [See current documentation](https://storybook.js.org/docs/essentials/backgrounds.md)                                 | [See addon versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/addons/backgrounds)                                                                                                                                                    | [See addon versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/addons/backgrounds)                                        |
|               | Toolbars and globals                            | [See current documentation](https://storybook.js.org/docs/essentials/toolbars-and-globals.md)                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/toolbar-guide)                                                                                                                                         | Non existing feature or undocumented                                                                                                                     |
| Configure     | Overview                                        | [See current documentation](https://storybook.js.org/docs/configure.md)                                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/overview)                                                                                                                                      | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/basics/writing-stories)                           |
|               | Integration/Frameworks                          | [See current documentation](https://storybook.js.org/docs/configure/integration/frameworks.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Integration/Framework support for frameworks    | [See current documentation](https://storybook.js.org/docs/configure/integration/frameworks-feature-support.md)       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Integration/Compilers                           | [See current documentation](https://storybook.js.org/docs/configure/integration/compilers.md)                        | See versioned documentation [here](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/custom-babel-config)                                                                                                                      | See versioned documentation [here](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/custom-babel-config)          |
|               | Integration/Typescript                          | [See current documentation](https://storybook.js.org/docs/configure/integration/typescript.md)                       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/typescript-config)                                                                                                                             | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/typescript-config)                 |
|               | Integration/Styling and CSS                     | [See current documentation](https://storybook.js.org/docs/configure/styling-and-css.md)                              | See versioned documentation                                                                                                                                                                                                                                          | See versioned documentation                                                                                                                              |
|               | Integration/Images and assets                   | [See current documentation](https://storybook.js.org/docs/configure/integration/images-and-assets.md)                | See versioned documentation                                                                                                                                                                                                                                          | See versioned documentation                                                                                                                              |
|               | Story rendering                                 | [See current documentation](https://storybook.js.org/docs/configure/story-rendering.md)                              | See versioned documentation [here](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/add-custom-head-tags) and [here](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/add-custom-body) | See versioned documentation [here](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/add-custom-head-tags)         |
|               | Story Layout                                    | [See current documentation](https://storybook.js.org/docs/configure/story-layout.md)                                 | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | User Interface/Features and behavior            | [See current documentation](https://storybook.js.org/docs/configure/user-interface/features-and-behavior.md)         | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/options-parameter)                                                                                                                             | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/options-parameter)                 |
|               | User Interface/Theming                          | [See current documentation](https://storybook.js.org/docs/configure/user-interface/theming.md)                       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/theming)                                                                                                                                       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/theming)                           |
|               | User Interface/Sidebar & URLS                   | [See current documentation](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls.md)              | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/options-parameter)                                                                                                                             | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/options-parameter)                 |
|               | Environment variables                           | [See current documentation](https://storybook.js.org/docs/configure/environment-variables.md)                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/env-vars)                                                                                                                                      | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/env-vars)                          |
| Builders      | Introduction                                    | [See current documentation](https://storybook.js.org/docs/builders.md)                                         | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Vite                                            | [See current documentation](https://storybook.js.org/docs/builders/vite.md)                                          | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Webpack                                         | [See current documentation](https://storybook.js.org/docs/builders/webpack.md)                                       | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/custom-webpack-config/index.md)                                                                                                                | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/custom-webpack-config/index.md)    |
|               | Builder API                                     | [See current documentation](https://storybook.js.org/docs/builders/builder-api.md)                                   | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
| Addons        | Introduction                                    | [See current documentation](https://storybook.js.org/docs/addons.md)                                           | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/addons/writing-addons)                                                                                                                                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/addons/writing-addons)                            |
|               | Install addons                                  | [See current documentation](https://storybook.js.org/docs/addons/install-addons.md)                                  | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/addons/using-addons/)                                                                                                                                         | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/addons/using-addons/)                             |
|               | Writing Addons                                  | [See current documentation](https://storybook.js.org/docs/addons/writing-addons.md)                                  | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/addons/writing-addons)                                                                                                                                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/addons/writing-addons)                            |
|               | Writing Presets                                 | [See current documentation](https://storybook.js.org/docs/addons/writing-presets.md)                                 | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/presets/writing-presets)                                                                                                                                      | Non existing feature or undocumented                                                                                                                     |
|               | Addons Knowledge Base                           | [See current documentation](https://storybook.js.org/docs/addons/addon-knowledge-base.md)                            | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/addons/writing-addons)                                                                                                                                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/addons/writing-addons)                            |
|               | Types of addons                                 | [See current documentation](https://storybook.js.org/docs/addons/addon-types.md)                                     | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Addons API                                      | [See current documentation](https://storybook.js.org/docs/addons/addons-api.md)                                      | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/addons/api)                                                                                                                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/addons/api)                                       |
| API           | @storybook/addon-docs/blocks/ArgTypes           | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Canvas             | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas.md)                        | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/ColorPalette       | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-colorpalette.md)                  | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Controls           | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-controls.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Description        | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-description.md)                   | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/IconGallery        | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-icongallery.md)                   | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Markdown           | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-markdown.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Meta               | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-meta.md)                          | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Primary            | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-primary.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Source             | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-source.md)                        | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Stories            | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-stories.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Story              | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-story.md)                         | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Subtitle           | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-subtitle.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Title              | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-title.md)                         | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Typeset            | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-typeset.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/Unstyled           | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-unstyled.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | @storybook/addon-docs/blocks/useOf              | [See current documentation](https://storybook.js.org/docs/api/doc-blocks/doc-block-useof.md)                         | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Stories/Component Story Format (see note below) | [See current documentation](https://storybook.js.org/docs/api/csf.md)                                          | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/formats/component-story-format)                                                                                                                               | Non existing feature or undocumented                                                                                                                     |
|               | ArgTypes                                        | [See current documentation](https://storybook.js.org/docs/api/arg-types.md)                                          | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/Overview                | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config.md)                            | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/framework               | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-framework.md)                  | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/stories                 | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-stories.md)                    | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/addons                  | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-addons.md)                     | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/babel                   | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-babel.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/babelDefault            | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-babel-default.md)              | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/build                   | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-build.md)                      | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/core                    | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-core.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/docs                    | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-docs.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/env                     | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-env.md)                        | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/features                | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-features.md)                   | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/indexers                | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-indexers.md)                   | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/logLevel                | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-log-level.md)                  | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/managerHead             | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-manager-head.md)               | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/previewAnnotations      | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-preview-annotations.md)        | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/previewBody             | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-preview-body.md)               | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/previewHead             | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-preview-head.md)               | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/refs                    | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-refs.md)                       | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/staticDirs              | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-static-dirs.md)                | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/swc                     | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-swc.md)                        | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/typescript              | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-typescript.md)                 | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/viteFinal               | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-vite-final.md)                 | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | `main.js` configuration/webpackFinal            | [See current documentation](https://storybook.js.org/docs/api/main-config/main-config-webpack-final.md)              | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | Frameworks                                      | [See current documentation](https://storybook.js.org/docs/api/new-frameworks.md)                                     | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
|               | CLI options                                     | [See current documentation](https://storybook.js.org/docs/api/cli-options.md)                                        | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/cli-options)                                                                                                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/cli-options)                       |

If you have stories written with the older `storiesOf` format, it was removed in Storybook 8.0 and is no longer maintained. We recommend that you migrate your stories to CSF. See the [migration guide](https://storybook.js.org/docs/releases/migration-guide.md#major-breaking-changes) for more information. However, if you need, you can still access the old `storiesOf` [documentation](https://github.com/storybookjs/storybook/blob/release/5.3/docs/src/pages/formats/storiesof-api/index.md) for reference.

## What icons are available for my toolbar or my addon?

With the [`@storybook/icons`](https://www.npmjs.com/package/@storybook/icons) package, you get a set of icons that you can use to customize your UI. Go through the [documentation](https://main--64b56e737c0aeefed9d5e675.chromatic.com/?path=/docs/introduction--docs) to see how the icons look and use it as a reference when writing your addon or defining your Storybook global types.

## I see a "No Preview" error with a Storybook production build

If you're using the `serve` package to verify your production build of Storybook, you'll get that error. It relates to how `serve` handles rewrites. For instance, `/iframe.html` is rewritten into `/iframe`, and you'll get that error.

We recommend that you use [http-server](https://www.npmjs.com/package/http-server) instead and use the following command to preview Storybook:

```shell
npx http-server storybook-static
```

Suppose you don't want to run the command above frequently. Add `http-server` as a development dependency and create a new script to preview your production build of Storybook.

## Can I use Storybook with Vue 2?

Vue 2 entered [End of Life](https://v2.vuejs.org/lts/) (EOL) on December 31, 2023, and is no longer supported by the Vue team. As a result, we've stopped supporting Vue 2 in Storybook 8 and above and will not be releasing any new versions that support it. We recommend upgrading your project to Vue 3, which Storybook fully supports. If that's not an option, you can still use Storybook with Vue 2 by installing the latest version of Storybook 7 with the following command:

```shell
npx storybook@^7 init
```

```shell
pnpm dlx storybook@^7 init
```

```shell
yarn dlx storybook@^7 init
```

## Why aren't my code blocks highlighted with Storybook MDX?

Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) you can use with your code blocks. Currently, there's a known limitation when you try to register a custom language to get syntax highlighting. We're working on a fix for this and will update this section once it's available.

## Why aren't my MDX styles working in Storybook?

Writing documentation with MDX can be troublesome, especially regarding how your code is formatted when using line breaks with code blocks. For example, this will break:

```mdx title="Example.mdx"
<style>{`
  .class1 {
    ...
  }

  .class2 {
    ...
  }
`}</style>
```

But this will work:

```mdx title="Example.mdx"
<style>
  {`
    .class1 {
      ...
    }

    .class2 {
      ...
    }
  `}
</style>
```

See the following [issue](https://github.com/mdx-js/mdx/issues/1945) for more information.

## Why are my mocked GraphQL queries failing with Storybook's MSW addon?

If you're working with Vue 3, you'll need to install [`@vue/apollo-composable`](https://www.npmjs.com/package/@vue/apollo-composable).

With Svelte, you'll need to install [`@rollup/plugin-replace`](https://www.npmjs.com/package/@rollup/plugin-replace) and update your `rollup.config` file to the following:

```js title="rollup.config.js"
// Boilerplate imports

const production = !process.env.ROLLUP_WATCH;

// Remainder rollup.config implementation

export default {
  input: 'src/main.js',
  output: {
    sourcemap: true,
    format: 'iife',
    name: 'app',
    file: 'public/build/bundle.js',
  },
  plugins: [
    // Other plugins

    // Configures the replace plugin to allow GraphQL Queries to work properly
    replace({
      'process.env.NODE_ENV': JSON.stringify('development'),
    }),
  ],
};
```

With Angular, the most common issue is the placement of the `mockServiceWorker.js` file. Use this [example](https://github.com/mswjs/examples/tree/main/examples/with-angular) as a point of reference.

## Can I use other GraphQL providers with Storybook's MSW addon?

Yes, check the [addon's examples](https://github.com/mswjs/msw-storybook-addon/tree/main/packages/docs/src/demos) to learn how to integrate different providers.

## Can I mock GraphQL mutations with Storybook's MSW addon?

No, currently, the MSW addon only has support for GraphQL queries. If you're interested in including this feature, open an issue in the [MSW addon repository](https://github.com/mswjs/msw-storybook-addon) and follow up with the maintainer.

## Why are my stories not showing up correctly when using certain characters?

Storybook allows you to use most characters while naming your stories. Still, specific characters (e.g., `#`) can lead to issues when Storybook generates the internal identifier for the story, leading to collisions and incorrectly outputting the correct story. We recommend using such characters sparsely.

## Why is Storybook's source loader returning undefined with curried functions?

This is a known issue with Storybook. If you're interested in getting it fixed, open an issue with a [working reproduction](https://storybook.js.org/docs/contribute/how-to-reproduce.md) so that it can be triaged and fixed in future releases.

## Why isn't Storybook's test runner working?

There's an issue with Storybook's test runner and the latest version of Jest (i.e., version 28), which prevents it from running effectively. As a workaround, you can downgrade Jest to the previous stable version (i.e., version 27), and you'll be able to run it. See the following [issue](https://github.com/storybookjs/test-runner/issues/99) for more information.

## How does Storybook handle environment variables?

Storybook has built-in support for [environment variables](https://storybook.js.org/docs/configure/environment-variables.md). By default, environment variables are only available in Node.js code and are not available in the browser as some variables should be kept secret (e.g., API keys) and **not** exposed to anyone visiting the published Storybook.

To expose a variable, you must preface its name with `STORYBOOK_`. So `STORYBOOK_API_URL` will be available in browser code but `API_KEY` will not. Additionally you can also customize which variables are exposed by setting the [`env`](https://storybook.js.org/docs/configure/environment-variables.md#using-storybook-configuration) field in the `.storybook/main.js` file.

Variables are set when JavaScript is compiled so when the development server is started or you build your Storybook. Environment variable files should not be committed to Git as they often contain secrets which are not safe to add to Git. Instead, add `.env.*` to your `.gitignore` file and set up the environment variables manually on your hosting provider (e.g., [GitHub](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)).
> Source: https://storybook.js.org/docs/faq
---