---
title: Storybook for Angular
hideRendererSelector: true
sidebar:
  order: 1
  title: Angular
---

Storybook for Angular is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [Angular](https://angular.io/) applications. It includes:

* 🧱 Uses Angular builders
* 🎛️ Compodoc integration
* 💫 and more!

## Requirements

* Angular ≥ 15.0 \< 20.0
* Webpack ≥ 5.0
* Storybook ≥ 8.0

## Getting started

### In a project without Storybook

Follow the prompts after running this command in your Angular project's root directory:

{/* prettier-ignore-start */}

<CodeSnippets path="create-command.md" />

{/* prettier-ignore-end */}

[More on getting started with Storybook.](../install.mdx)

### In a project with Storybook

This framework is designed to work with Storybook 7+. If you’re not already using v7, upgrade with this command:

{/* prettier-ignore-start */}

<CodeSnippets path="storybook-upgrade.md" />

{/* prettier-ignore-end */}

#### Automatic migration

When running the `upgrade` command above, you should get a prompt asking you to migrate to `@storybook/angular`, which should handle everything for you. In case that auto-migration does not work for your project, refer to the manual migration below.

#### Manual migration

First, install the framework:

{/* prettier-ignore-start */}

<CodeSnippets path="angular-install.md" />

{/* prettier-ignore-end */}

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

{/* prettier-ignore-start */}

<CodeSnippets path="angular-add-framework.md" />

{/* prettier-ignore-end */}

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
          }
        }
      }
    }
  }
}
```

## Run Storybook

To run Storybook for a particular project, please 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>`).

## Setup 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](../../writing-docs/autodocs.mdx) 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](../../essentials/controls.mdx).

### 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:

```ts title=".storybook/preview.ts"
import type { Preview } from '@storybook/angular';

// 👇 Add these
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';
setCompodocJson(docJson);

const preview: Preview = {};
export default preview;
```

## `applicationConfig` decorator

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](../../writing-stories/decorators.mdx) to all stories for that component. This will provide them with the [bootstrapApplication function](https://angular.io/guide/standalone-components#configuring-dependency-injection), used to bootstrap the component in Storybook.

```ts title="ChipsModule.stories.ts"
import { Meta, applicationConfig, StoryObj } from '@storybook/angular';

import { BrowserAnimationsModule, provideAnimations } from '@angular/platform-browser/animations';
import { importProvidersFrom } from '@angular/core';

import { ChipsModule } from './angular-src/chips.module';

const meta: Meta<ChipsModule> = {
  component: ChipsModule,
  decorators: [
    // Apply application config to all stories
    applicationConfig({
      // List of providers and environment providers that should be available to the root component and all its children.
      providers: [
        ...
        // Import application-wide providers from a module
        importProvidersFrom(BrowserAnimationsModule)
        // Or use provide-style functions if available instead, e.g.
        provideAnimations()
      ],
    }),
  ],
};

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

export const WithCustomApplicationProvider: Story = {
  render: () => ({
    // Apply application config to a specific story
    applicationConfig: {
      // The providers will be merged with the ones defined in the applicationConfig decorator's providers array of the global meta object
      providers: [...],
    }
  })
}
```

## `moduleMetadata` decorator

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

```ts title="YourComponent.stories.ts"
import { Meta, moduleMetadata, StoryObj } from '@storybook/angular';

import { YourComponent } from './your.component';

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 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@next automigrate` to try letting Storybook detect and automatically fix your configuration. Otherwise, you can follow the next steps to adjust your configuration manually.

#### Do you have only one Angular project in your workspace?

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

Second, adjust your `package.json` script section. Usually, it will look like this:

```jsonc title="package.json"
{
  "scripts": {
    "storybook": "start-storybook -p 6006", // or `storybook dev -p 6006`
    "build-storybook": "build-storybook" // or `storybook build`
  }
}
```

Now, you can run Storybook with `ng run <your-project>:storybook` and build it with `ng run <your-project>:build-storybook`. Adjust the scripts in your `package.json` accordingly.

```json title="package.json"
{
  "scripts": {
    "storybook": "ng run <project-name>:storybook",
    "build-storybook": "ng run <project-name>:build-storybook"
  }
}
```

  Also, `compodoc` is now built into `@storybook/angular`; you don't have to call it explicitly. If we're running `compodoc` in your `package.json` scripts like this:

```json 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"
  }
}
```

Change it to:

```json title="package.json"
{
  "scripts": {
    "storybook": "ng run <project-name>:storybook",
    "build-storybook": "ng run <project-name>:build-storybook"
  }
}
```

#### I have multiple projects in my Angular workspace

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

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](../../sharing/storybook-composition.mdx).

### 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](../../writing-docs/build-documentation.mdx#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](../../configure/styling-and-css.mdx#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: [silly, verbose, info (default), warn, error, silent]. <br /> `"loglevel": "info"`                                                       |
| `"sourceMap"`                | Configure [sourcemaps](https://angular.io/guide/workspace-config#source-map-configuration.). <br /> `"sourceMap": true`                                                                         |

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

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

## API

### Options

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

```js title=".storybook/main.ts"
import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  framework: {
    name: '@storybook/angular',
    options: {
      // ...
    },
  },
};
```

The available options are:

#### `builder`

Type: `Record<string, any>`

Configure options for the [framework's builder](../../api/main-config/main-config-framework.mdx#optionsbuilder). For this framework, available options can be found in the [Webpack builder docs](../../builders/webpack.mdx).