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: https://github.com/storybookjs/storybook/blob/master/addons/docs/docs/theming.md

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';

addons.setConfig({
  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: 'https://example.com',
  brandImage: 'https://placehold.it/350x150',
});

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

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

addons.setConfig({
  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: 'https://example.com',
  brandImage: 'https://placehold.it/350x150',
});

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: {
...chromeLight,
BASE_FONT_FAMILY: typography.fonts.mono,
BASE_BACKGROUND_COLOR: 'transparent',
}

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 }) => ({
background: theme.background.app,
width: 0,
}));

Or with template literals:

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