Theming Storybook

Edit this page

Storybook is theme-able!

Note that theming storybook changed recently, to be in manager.js (introduced in 5.3). But addon-docs is not yet compatible with this new way of configuring the theme.

See here how to use theme storybook in a way that addon-docs will be themed as well:

Global theming

It’s possible to theme Storybook globally.

We’ve created two basic themes that look good out of the box: “normal” (a light theme) and “dark” (a dark theme). Unless you’ve set your preferred color scheme as dark Storybook will use the light theme as default.

Make sure you have installed @storybook/addons and @storybook/theming packages.

npm install @storybook/addons --save-dev
npm install @storybook/theming --save-dev

As an example, you can tell Storybook to use the “dark” theme by modifying .storybook/manager.js:

import { addons } from '@storybook/addons';
import { themes } from '@storybook/theming';

  theme: themes.dark,

When setting a theme, set a full theme object. The theme is replaced, not combined.

Read on for more on how to create your own 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:

First create a new file in .storybook called yourTheme.js.

Next paste the code below and tweak the variables.

import { create } from '@storybook/theming/create';

export default create({
  base: 'light',

  colorPrimary: 'hotpink',
  colorSecondary: 'deepskyblue',

  // UI
  appBg: 'white',
  appContentBg: 'silver',
  appBorderColor: 'grey',
  appBorderRadius: 4,

  // Typography
  fontBase: '"Open Sans", sans-serif',
  fontCode: 'monospace',

  // Text colors
  textColor: 'black',
  textInverseColor: 'rgba(255,255,255,0.9)',

  // Toolbar default and active colors
  barTextColor: 'silver',
  barSelectedColor: 'black',
  barBg: 'hotpink',

  // Form colors
  inputBg: 'white',
  inputBorder: 'silver',
  inputTextColor: 'black',
  inputBorderRadius: 4,

  brandTitle: 'My custom storybook',
  brandUrl: '',
  brandImage: '',

Finally, import your theme into .storybook/manager.js and add it to your Storybook parameters.

import { addons } from '@storybook/addons';
import yourTheme from './yourTheme';

  theme: yourTheme,

The storybook/theming package is built using TypeScript, so this should help create a valid theme for typescript users. The types are part of the package itself.

Many theme variables are optional, the base property is NOT. This is a perfectly valid theme:

import { create } from '@storybook/theming/create';

export default create({
  base: 'light',

  brandTitle: 'My custom storybook',
  brandUrl: '',
  brandImage: '',

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 and other popular addons so your users have a consistent experience.

For example, the popular Actions addon uses react-inspector which has themes of its own. Supply additional theme variables to style it like so:

addonActionsTheme: {
BASE_FONT_FAMILY: typography.fonts.mono,

Using the theme for addon authors

For a native Storybook experience, we encourage addon authors to reuse the theme variables above. The theming engine relies on emotion, a CSS-in-JS library.

import { styled } from '@storybook/theming';

Use the theme variables in object notation:

const Component = styled.div(({ theme }) => ({
width: 0,

Or with template literals:

const Component = styled.div`
background: `${props =>}`
width: 0;