0
# Storybook Addon Themes
1
2
Storybook Addon Themes enables theme switching functionality within the Storybook preview environment. It provides multiple decorators for different theming strategies including CSS classes, data attributes, and JSX providers, making it compatible with popular styling solutions like styled-components, emotion, Material-UI, Tailwind CSS, and Bootstrap.
3
4
## Package Information
5
6
- **Package Name**: @storybook/addon-themes
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D @storybook/addon-themes`
10
- **Storybook Version**: 7.0 or later
11
- **Peer Dependencies**: storybook (workspace:^)
12
13
## Core Imports
14
15
```typescript
16
import {
17
withThemeByClassName,
18
withThemeByDataAttribute,
19
withThemeFromJSXProvider,
20
DecoratorHelpers,
21
type ThemesTypes
22
} from "@storybook/addon-themes";
23
24
// Default export for addon registration
25
import addonThemes from "@storybook/addon-themes";
26
```
27
28
For CommonJS:
29
30
```javascript
31
const {
32
withThemeByClassName,
33
withThemeByDataAttribute,
34
withThemeFromJSXProvider,
35
DecoratorHelpers
36
} = require("@storybook/addon-themes");
37
38
// Default export
39
const addonThemes = require("@storybook/addon-themes").default;
40
```
41
42
## Basic Usage
43
44
Add the addon to your Storybook configuration:
45
46
```javascript
47
// .storybook/main.js
48
export default {
49
addons: ['@storybook/addon-themes'],
50
};
51
```
52
53
Configure theme switching in your preview:
54
55
```javascript
56
// .storybook/preview.js
57
import { withThemeByClassName } from '@storybook/addon-themes';
58
59
export const decorators = [
60
withThemeByClassName({
61
themes: {
62
light: 'light-theme',
63
dark: 'dark-theme',
64
},
65
defaultTheme: 'light',
66
}),
67
];
68
```
69
70
## Architecture
71
72
The addon is built around several key components:
73
74
- **Theme Decorators**: Three main decorators for different theming approaches (CSS classes, data attributes, JSX providers)
75
- **Helper Functions**: Utilities for accessing theme state and creating custom decorators
76
- **Manager Integration**: UI components for theme switching in the Storybook toolbar
77
- **Global State Management**: Theme state synchronization between manager and preview
78
- **Event System**: Communication channel for theme registration and updates
79
80
## Capabilities
81
82
### CSS Class-Based Theming
83
84
Theme switching by applying CSS classes to parent elements. Ideal for CSS frameworks and traditional stylesheet-based themes.
85
86
```typescript { .api }
87
function withThemeByClassName<TRenderer extends Renderer = Renderer>(
88
config: ClassNameStrategyConfiguration
89
): DecoratorFunction<TRenderer>;
90
91
interface ClassNameStrategyConfiguration {
92
themes: Record<string, string>;
93
defaultTheme: string;
94
parentSelector?: string;
95
}
96
```
97
98
[CSS Class Theming](./css-class-theming.md)
99
100
### Data Attribute-Based Theming
101
102
Theme switching by setting data attributes on parent elements. Perfect for CSS custom properties and attribute-based selectors.
103
104
```typescript { .api }
105
function withThemeByDataAttribute<TRenderer extends Renderer = any>(
106
config: DataAttributeStrategyConfiguration
107
): DecoratorFunction<TRenderer>;
108
109
interface DataAttributeStrategyConfiguration {
110
themes: Record<string, string>;
111
defaultTheme: string;
112
parentSelector?: string;
113
attributeName?: string;
114
}
115
```
116
117
[Data Attribute Theming](./data-attribute-theming.md)
118
119
### JSX Provider-Based Theming
120
121
Theme switching using JSX provider components and theme objects. Designed for component libraries like styled-components, emotion, and Material-UI.
122
123
```typescript { .api }
124
function withThemeFromJSXProvider<TRenderer extends Renderer = any>(
125
config: ProviderStrategyConfiguration
126
): DecoratorFunction<TRenderer>;
127
128
interface ProviderStrategyConfiguration {
129
Provider?: any;
130
GlobalStyles?: any;
131
defaultTheme?: string;
132
themes?: Record<string, any>;
133
}
134
```
135
136
[JSX Provider Theming](./jsx-provider-theming.md)
137
138
### Custom Decorator Helpers
139
140
Utilities for building custom theme decorators when the built-in decorators don't meet specific requirements.
141
142
```typescript { .api }
143
namespace DecoratorHelpers {
144
function pluckThemeFromContext(context: StoryContext): string;
145
function initializeThemeState(themeNames: string[], defaultTheme: string): void;
146
function useThemeParameters(context?: StoryContext): ThemesParameters;
147
}
148
```
149
150
[Custom Decorators](./custom-decorators.md)
151
152
### Default Export
153
154
The package's default export is a function that creates a Storybook addon definition for use with Storybook's internal addon system.
155
156
```typescript { .api }
157
/**
158
* Creates a Storybook addon definition with theme support
159
* @returns Storybook addon definition
160
*/
161
function default(): PreviewAddon<ThemesTypes>;
162
```
163
164
This export is automatically used by Storybook when the addon is registered in your `.storybook/main.js` addons array. You typically don't need to import or use this directly unless you're building custom addon integrations.
165
166
## Types
167
168
```typescript { .api }
169
interface ThemesTypes {
170
parameters: ThemesParameters;
171
globals: ThemesGlobals;
172
}
173
174
interface ThemesParameters {
175
themes?: {
176
disable?: boolean;
177
themeOverride?: string;
178
};
179
}
180
181
interface ThemesGlobals {
182
theme?: string;
183
}
184
185
interface ThemeAddonState {
186
themesList: string[];
187
themeDefault?: string;
188
}
189
```
190
191
## Internal Constants
192
193
The addon exports several internal constants used for its operation. These are not part of the public API and should not be used directly in consuming code:
194
195
- `PARAM_KEY` - Parameter key for theme configuration
196
- `GLOBAL_KEY` - Global key for theme state
197
- `ADDON_ID` - Unique addon identifier
198
- `THEME_SWITCHER_ID` - Theme switcher component identifier
199
- `THEMING_EVENTS` - Event constants for theme communication
200
201
These constants are implementation details and may change between releases.