theming.md

title
Theming

Storybook is theme-able using a lightweight theming API.

Global theming

It's possible to theme Storybook globally.

Storybook includes two 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.

yarn add --dev @storybook/addons @storybook/theming

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

<CodeSnippets paths={[ 'common/storybook-manager-dark-theme.js.mdx', ]} />

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

Theming docs

Storybook Docs uses the same theme system as Storybook’s UI, but is themed independently from the main UI.

Supposing you have a Storybook theme defined for the main UI in .storybook/manager.js:

<CodeSnippets paths={[ 'common/storybook-manager-dark-theme.js.mdx', ]} />

Here's how you'd specify the same theme for docs in .storybook/preview.js:

<CodeSnippets paths={[ 'common/storybook-preview-docs-dark-theme.js.mdx', ]} />

Continue to read if you want to learn how to create your 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:

Inside your .storybook directory, create a new file called YourTheme.js and add the following:

<CodeSnippets paths={[ 'common/storybook-theme-example-variables.ts.mdx', ]} />

If you're using brandImage to add your own custom logo, you can use any of the most common image formats.

Above we're creating a new theme that will:

• Use Storybook's light theme as a baseline.
• Replace Storybook's logo in the sidebar with our own (defined in the brandImage variable).
• Add custom branding information.

Finally we'll need to import the theme into Storybook. Create a new file called manager.js in your .storybook directory and add the following:

<CodeSnippets paths={[ 'common/storybook-manager-custom-theme.js.mdx', ]} />

Adjust your storybook script in your package.json and include the --no-manager-cache flag. For instance:

{
  "scripts":{
    "storybook": "start-storybook -p 6006 --no-manager-cache",
  },
}

Now your custom theme will replace Storybook's default theme and you'll see a similar set of changes in the UI.

Note: Once you're finished configuring the theme, remove the flag --no-manager-cache from the storybook script, otherwise loading times can be severely impacted.

Let's take a look at more complex example. Copy the code below and paste it in .storybook/YourTheme.js.

<CodeSnippets paths={[ 'common/your-theme.js.mdx', ]} />

Above we're updating the theme with the following changes:

• A custom color palette (defined in the app and color variables).
• Custom fonts (defined in the font and text variables).

With the new changes introduced, the custom theme should yield a similar result.

Many theme variables are optional, the base property is NOT.

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.

CSS escape hatches

The Storybook theme API is narrow by design. If you want to have fine-grained control over the CSS, all of the UI and Docs components are tagged with class names to make this possible. This is advanced usage: use at your own risk.

To style these elements, insert style tags into:

• For Storybook’s UI, use .storybook/manager-head.html
• For Storybook Docs, use .storybook/preview-head.html

Similar to changing the preview’s head tag, .storybook/manager-head.html allows you to inject code into the manager side, which can be useful to adding styles for your theme that target Storybook’s HTML.

WARNING: we don’t make any guarantees about the structure of Storybook’s HTML and it could change at any time. Consider yourself warned!

MDX component overrides

If you're using MDX for docs, there's one more level of themability. MDX allows you to completely override the components that are rendered from Markdown using a components parameter. This is an advanced usage that we don't officially support in Storybook, but it's a powerful mechanism if you need it.

Here's how you might insert a custom code renderer for code blocks on the page, in .storybook/preview.js:

<CodeSnippets paths={[ 'common/storybook-preview-custom-code-renderer.js.mdx', ]} />

You can even override a Storybook block component.

Here's how you might insert a custom <Canvas /> block:

<CodeSnippets paths={[ 'common/storybook-preview-custom-canvas.js.mdx', ]} />

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

<CodeSnippets paths={[ 'common/storybook-preview-extended-theme-variables.js.mdx', ]} />

Using the theme for addon authors

Reuse the theme variables above for a native Storybook developer experience. The theming engine relies on emotion, a CSS-in-JS library.

<CodeSnippets paths={[ 'common/storybook-theming-styled-import.js.mdx', ]} />

Use the theme variables in object notation:

<CodeSnippets paths={[ 'react/component-styled-variables-object-notation.js.mdx', ]} />

Or with template literals:

<CodeSnippets paths={[ 'react/component-styled-variables-template-literals.js.mdx', ]} />