storybook-addon-theme
v10.0.11
Published
A lightweight Storybook addon for theme switching, keeping Manager UI, Canvas stories, and Docs pages in sync.
Maintainers
xvivx.luckReadme
storybook-addon-theme
A lightweight Storybook addon for synchronised theme switching across the Manager UI, Canvas stories, and Docs pages.
Install
Use your preferred package manager:
# npm
npm install storybook-addon-themeUsage
Register the addon in your Storybook main configuration (for example, .storybook/main.js):
CSF3
// .storybook/main.ts
import { defineMain } from '@storybook/react-vite/node';
export default defineMain({
addons: ['storybook-addon-theme'],
});
// custom addon
export default defineMain({
addons: [
{
name: 'storybook-addon-theme',
options: {
decorator: true,
docs: true,
},
},
],
});CSF Next
// .storybook/main.ts
import { defineMain } from '@storybook/react-vite/node';
export default defineMain({
addons: ['storybook-addon-theme'],
});
// .storybook/preview.tsx
import { definePreview } from '@storybook/react-vite';
import addTheme from 'storybook-addon-theme';
const preview = definePreview({
addons: [addTheme()],
});
// custom preview
const preview = definePreview({
addons: [addTheme({ decorator: true, docs: true })],
});Options
decorator: Whether to use the built-in decorator. When enabled, switching themes will toggle adarkclass on the<html>element.docs: Whether to use the Docs container integration. When enabled, the addon will pass the selected theme toDocsContainerso documentation pages can match the current theme.
If you use Tailwind CSS for your component library, the default behavior (toggling the dark class on <html>) will typically be sufficient.
Customization
You can keep the addon enabled but customize how your preview and docs respond to theme changes. Below is an example preview.tsx that shows how to make stories and Docs pages react to the selected theme.
import React, { useEffect } from 'react';
import { definePreview } from '@storybook/react-vite';
import { DocsContainer } from '@storybook/addon-docs/blocks';
import { themes } from 'storybook/theming';
import addTheme, { useTheme } from 'storybook-addon-theme';
const preview = definePreview({
addons: [addTheme({ docs: false, decorator: false })],
decorators: [
// Make stories respond to theme changes
(Story) => {
const theme = useTheme();
useEffect(() => {
document.documentElement.classList.toggle('dark', theme === 'dark');
}, [theme]);
return <Story />;
},
],
parameters: {
docs: {
// Make Docs pages respond to theme changes by passing the appropriate theme
container: (props) => {
const theme = useTheme();
return <DocsContainer {...props} theme={theme === 'dark' ? themes.dark : themes.light} />;
},
},
},
});
export default preview;Notes
- The addon focuses on synchronising theme selection across Storybook's Manager, Canvas, and Docs UI.
- Keep
decoratorenabled if you want automatic DOM class toggling (useful for Tailwind dark mode). - Keep
docsenabled if you want Docs pages to reflect the selected theme automatically.