storybook/docs/configure/styling-and-css.md

title
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. These files will be subject to HMR, so you can see your changes without restarting your Storybook server.

<CodeSnippets paths={[ 'common/storybook-preview-import-global-styles.js.mdx', 'common/storybook-preview-import-global-styles.ts.mdx', ]} />

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. However, these files will not be subject to HMR, so you'll need to restart your Storybook server to see your changes.

<CodeSnippets paths={[ 'common/storybook-preview-head-import-global-styles.html.mdx', ]} />

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.

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 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.

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 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.

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 to help you configure these tools. Or if you'd prefer, you can customize Storybook's webpack configuration yourself 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.

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 file. We recommend including any assets with your Storybook if possible, in which case you likely want to configure the static file location.

.storybook/preview.ts

If you're using something like fontsource for your fonts, you can import the needed css files in your .storybook/preview.ts file.

Storybook for Angular relies on the Angular CLI to build your stories. This means that you can use any CSS preprocessor that the Angular CLI supports. You can read more about this in the Angular CLI documentation.

Global styles

To add global styles to your Storybook, you can add them to the styles array in your angular.json file. This will add the styles to the preview iframe where your components render, not the Storybook Manager UI.

Don't forget to also add your global styles to your build-storybook target in your angular.json file. This will ensure that your global styles are included in the static build of your Storybook as well.

{
  "storybook": {
    "builder": "@storybook/angular:start-storybook",
    "options": {
      "configDir": ".storybook",
      "browserTarget": "angular-latest:build",
      "compodoc": true,
      "compodocArgs": ["-e", "json", "-d", "."],
      "port": 6006,
      "styles": [
        // Add your global styles here
        "@angular/material/prebuilt-themes/indigo-pink.css",
        "@fontsource/roboto/300.css",
        "@fontsource/roboto/400.css",
        "@fontsource/roboto/500.css",
        "@fontsource/roboto/700.css",
        "@fontsource/material-icons",
        "src/styles.scss"
      ]
    }
  },
  "build-storybook": {
    "builder": "@storybook/angular:build-storybook",
    "options": {
      "configDir": ".storybook",
      "browserTarget": "angular-latest:build",
      "compodoc": true,
      "compodocArgs": ["-e", "json", "-d", "."],
      "styles": [
        // Add your global styles here
        "@angular/material/prebuilt-themes/indigo-pink.css",
        "@fontsource/roboto/300.css",
        "@fontsource/roboto/400.css",
        "@fontsource/roboto/500.css",
        "@fontsource/roboto/700.css",
        "@fontsource/material-icons",
        "src/styles.scss"
      ],
      "outputDir": "storybook-static"
    }
  }
}

Troubleshooting

If you're working with Storybook and Nx libraries, you can extend your project's configuration (i.e., project.json) and provide the application's styles.

For earlier Nx versions (before 14.1.8), your configuration would look like this:

 "build-storybook": {
    "executor": "@nrwl/storybook:build",
    "outputs": ["{options.outputPath}"],
    "options": {
      "uiFramework": "@storybook/angular",
      "outputPath": "dist/storybook/example-lib",
      "config": {
        "configFolder": "libs/example-lib/storybook/.storybook"
      },
      "projectBuildConfig": "example-lib:build-storybook",
      "styles": ["apps/example-app/src/styles.scss"]
    }
  }

Starting with version 14.1.8, Nx uses the Storybook builder directly, which means any configuration supplied to the builder also applies to the NX setup. If you're working with a library, you'll need to configure the styling options ( e.g., preprocessors) inside the build-storybook options configuration object. For example:

    "storybook": {
      "executor": "@storybook/angular:start-storybook",
      "options": {
        "configDir": "apps/example-lib/.storybook",
        "browserTarget": "example-lib:build-storybook",
      },
    },
    "build-storybook": {
      "executor": "@storybook/angular:build-storybook",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputDir": "dist/storybook/example-lib",
        "configDir": "apps/example-lib/.storybook",
        "browserTarget": "example-lib:build-storybook",
        "styles": [".storybook/custom-styles.scss"],
        "stylePreprocessorOptions": {
          "includePaths": [
            "libs/design-system/src/lib"
          ]
        }
      }
    }

When Nx runs, it will load Storybook's configuration and styling based on storybook.browserTarget.