# @carbon/storybook-addon-theme

> Carbon theme switcher for Storybook

Latest version **2.27.0** (published 2025-10-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @carbon/storybook-addon-theme
pnpm add @carbon/storybook-addon-theme
yarn add @carbon/storybook-addon-theme
bun add @carbon/storybook-addon-theme
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.27.0 |
| Published | 2025-10-29 |
| First published | 2020-11-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 32.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 133 |
| Maintainers | leechase, carbon-bot, mattgallo |
| Keywords | addon, carbon, theme, storybook, carbon design system, carbon community, carbon for cloud & cognitive, carbon for ibm products |

## Links

- npm: https://www.npmjs.com/package/@carbon/storybook-addon-theme
- Repository: https://github.com/carbon-design-system/ibm-products
- Homepage: https://github.com/storybookjs/storybook#readme
- Issues: https://github.com/carbon-design-system/ibm-products/issues
- npm.io page: https://npm.io/package/@carbon/storybook-addon-theme

## Dependencies (10)

- [global](https://npm.io/package/global.md) ^4.4.0
- [core-js](https://npm.io/package/core-js.md) ^3.41.0
- [@storybook/api](https://npm.io/package/@storybook/api.md) 7.6.17
- [@ibm/telemetry-js](https://npm.io/package/@ibm/telemetry-js.md) ^1.9.1
- [@storybook/addons](https://npm.io/package/@storybook/addons.md) 7.6.17
- [@storybook/theming](https://npm.io/package/@storybook/theming.md) ^8.6.6
- [@storybook/client-api](https://npm.io/package/@storybook/client-api.md) 7.6.17
- [@storybook/components](https://npm.io/package/@storybook/components.md) ^8.6.6
- [@storybook/core-events](https://npm.io/package/@storybook/core-events.md) ^8.6.6
- [@storybook/client-logger](https://npm.io/package/@storybook/client-logger.md) ^8.6.6

## Recent versions

- 2.27.0 (latest) — 2025-10-29
- 2.27.0-rc.0 (next) — 2025-10-27
- 2.3.0-canary.45 (canary) — 2024-12-02
- 2.0.0-rc.0 (alpha) — 2023-06-12
- 2.26.0 — 2025-10-15
- 2.26.0-rc.0 — 2025-10-13
- 2.25.0 — 2025-10-01
- 2.25.0-rc.0 — 2025-09-29
- 2.24.0 — 2025-09-17
- 2.24.0-rc.0 — 2025-09-15
- 2.23.0 — 2025-09-03
- 2.23.0-rc.0 — 2025-09-02
- 2.22.0 — 2025-08-20
- 2.22.0-rc.0 — 2025-08-18
- 2.21.0 — 2025-08-06
- … 124 more at https://npm.io/package/@carbon/storybook-addon-theme/versions

## README

# Storybook addon for Carbon themes

This addon for storybook allows you to change the theme used with Carbon
Components!

## Supports

- React
- Vue

No reason to suspect others are not supported, but have not been tested. If you
use with another framework then please post an update to the README.md.

## Install

```sh
npm install --save-dev @carbon/storybook-addon-theme
yarn install --dev @carbon/storybook-addon-theme
```

## Requirements

- Use of Carbon Components
- Use of Custom CSS Properties feature flag

## 🙌 Contributing

We are always looking for contributors to help us fix bugs, build new features,
or help us improve the project documentation. If you're interested, definitely
check out our
[Contributing Guide](https://github.com/carbon-design-system/ibm-products/blob/master/.github/CONTRIBUTING.md)
and
[Carbon's Developer Handbook](https://github.com/carbon-design-system/carbon/blob/master/docs/developer-handbook.md)!
👀

## Usage

`.storybook/main.js`:

```js
module.exports = {
  // other addons...
  addons: ['@carbon/storybook-addon-theme/preset.js'],
};
```

### Global Decorator

`.storybook/preview.js`:

```js
import { withCarbonTheme } from '@carbon/storybook-addon-theme/withCarbonTheme';
import {
  PARAM_KEY as CARBON_THEME_PARAM_KEY,
  CARBON_THEMES,
} from '@carbon/storybook-addon-theme/constants';

const decorators = [
  /// other decorators...
  withCarbonTheme,
];

const globals = {
  // other globals...
  // default value of the theme selector
  [CARBON_THEME_PARAM_KEY]: CARBON_THEMES.g10,
};

export { decorators, globals };
```

## SCSS

`.storybook/index.scss`

### Carbon 11

```scss
@use '@carbon/styles' as styles;
@use '@carbon/styles/scss/theme' as *;

[data-carbon-theme] {
  @include styles.theme(styles.$white);

  /* make sure background and color are set if theme in use */
  background-color: $background;
  color: $text-primary;
}

[data-carbon-theme='g10'],
.sb--use-carbon-theme-g10 {
  @include styles.theme(styles.$g10);
}

[data-carbon-theme='g90'],
.sb--use-carbon-theme-g90 {
  @include styles.theme(styles.$g90);
}

[data-carbon-theme='g100'],
.sb--use-carbon-theme-g100 {
  @include styles.theme(styles.$g100);
}
```

### Carbon 10

```SCSS
// Must happen before styles are loaded
$feature-flags: (
  ui-shell: true,
  grid-columns-16: true,
  enable-css-custom-properties: true
);

@import "carbon-components/scss/globals/scss/styles";
@import "@carbon/themes/scss/themes";

[data-carbon-theme] {
  background: $ui-background;
  color: $ui-01;

  @include carbon--theme(
    $theme: $carbon--theme--white,
    $emit-custom-properties: true
  );
}

[data-carbon-theme="g10"] {
  @include carbon--theme(
    $theme: $carbon--theme--g10,
    $emit-custom-properties: true
  );
}

[data-carbon-theme="g90"] {
  z-index: 90;
  @include carbon--theme(
    $theme: $carbon--theme--g90,
    $emit-custom-properties: true
  );
}

[data-carbon-theme="g100"] {
  @include carbon--theme(
    $theme: $carbon--theme--g100,
    $emit-custom-properties: true
  );
}
```

## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized metrics
data. By installing this package as a dependency you are agreeing to telemetry
collection. To opt out, see
[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
For more information on the data being collected, please see the
[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).

---
_Source: https://npm.io/package/@carbon/storybook-addon-theme · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
