0
# Configuration
1

2
Comprehensive configuration options for customizing Storybook Dark Mode behavior, themes, and CSS class management through Storybook parameters.
3

4
## Capabilities
5

6
### Dark Mode Parameters
7

8
Configuration object for customizing dark mode behavior in `.storybook/preview.js`. Parameters are passed as a partial DarkModeStore object.
9

10
```typescript { .api }
11
/**
12
 * Dark mode configuration parameters
13
 * All properties are optional and will be merged with default values
14
 */
15
type DarkModeParameters = Partial<DarkModeStore>;
16

17
interface DarkModeStore {
18
  /** Initial theme preference - takes precedence over OS preference */
19
  current?: 'light' | 'dark';
20
  /** Custom dark theme configuration object */
21
  dark?: ThemeVars;
22
  /** Custom light theme configuration object */ 
23
  light?: ThemeVars;
24
  /** CSS class(es) applied to target elements in dark mode */
25
  darkClass?: string | string[];
26
  /** CSS class(es) applied to target elements in light mode */
27
  lightClass?: string | string[];
28
  /** CSS selector for target element in preview iframe */
29
  classTarget?: string;
30
  /** Whether to apply theme classes to preview iframe content */
31
  stylePreview?: boolean;
32
  /** Whether user has manually set a theme preference (internal) */
33
  userHasExplicitlySetTheTheme?: boolean;
34
}
35
```
36

37
### Theme Configuration
38

39
Override default Storybook themes with custom styling.
40

41
```typescript { .api }
42
/**
43
 * Storybook theme configuration object
44
 * Extends @storybook/theming ThemeVars interface
45
 */
46
interface ThemeVars {
47
  appBg?: string;
48
  appContentBg?: string;
49
  appBorderColor?: string;
50
  appBorderRadius?: number;
51
  fontBase?: string;
52
  fontCode?: string;
53
  textColor?: string;
54
  barTextColor?: string;
55
  barSelectedColor?: string;
56
  barBg?: string;
57
  inputBg?: string;
58
  inputBorder?: string;
59
  inputTextColor?: string;
60
  inputBorderRadius?: number;
61
  // ... additional Storybook theme properties
62
}
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
import { themes } from '@storybook/theming';
69

70
export const parameters = {
71
  darkMode: {
72
    // Custom dark theme
73
    dark: { 
74
      ...themes.dark, 
75
      appBg: '#1a1a1a',
76
      appContentBg: '#2d2d2d',
77
      textColor: '#ffffff'
78
    },
79
    // Custom light theme
80
    light: { 
81
      ...themes.normal, 
82
      appBg: '#f8f9fa',
83
      appContentBg: '#ffffff',
84
      textColor: '#333333'
85
    }
86
  }
87
};
88
```
89

90
### Initial Theme Settings
91

92
Control which theme is active when Storybook first loads.
93

94
**Theme Precedence Order:**
95
1. User's previously saved preference (localStorage)
96
2. `current` parameter value
97
3. OS color scheme preference
98
4. Default light theme
99

100
```javascript
101
export const parameters = {
102
  darkMode: {
103
    // Force light theme on initial load
104
    current: 'light',
105
    // Or force dark theme
106
    current: 'dark'
107
  }
108
};
109
```
110

111
### CSS Class Management
112

113
Customize CSS classes applied to manager and preview elements for theme styling.
114

115
```typescript { .api }
116
/**
117
 * CSS class configuration for theme styling
118
 */
119
interface ClassConfiguration {
120
  /** Class(es) applied in dark mode - can be string or array */
121
  darkClass?: string | string[];
122
  /** Class(es) applied in light mode - can be string or array */
123
  lightClass?: string | string[];
124
  /** CSS selector for target element in preview iframe */
125
  classTarget?: string;
126
}
127
```
128

129
**Default Values:**
130
- `darkClass`: `['dark']`
131
- `lightClass`: `['light']`
132
- `classTarget`: `'body'`
133

134
**Usage Examples:**
135

136
```javascript
137
export const parameters = {
138
  darkMode: {
139
    // Single class names
140
    darkClass: 'theme-dark',
141
    lightClass: 'theme-light',
142
    
143
    // Multiple classes
144
    darkClass: ['dark', 'high-contrast'],
145
    lightClass: ['light', 'standard-contrast'],
146
    
147
    // Target different element
148
    classTarget: 'html'  // Apply classes to <html> instead of <body>
149
  }
150
};
151
```
152

153
### Preview Iframe Styling
154

155
Control whether theme classes are applied to the preview iframe content.
156

157
```typescript { .api }
158
/**
159
 * Preview styling configuration
160
 */
161
interface PreviewStylingConfig {
162
  /** Whether to apply theme classes to preview iframe */
163
  stylePreview?: boolean;
164
  /** CSS selector for target element within preview iframe */
165
  classTarget?: string;
166
}
167
```
168

169
**Usage Examples:**
170

171
```javascript
172
export const parameters = {
173
  darkMode: {
174
    // Enable preview iframe styling
175
    stylePreview: true,
176
    // Apply classes to specific element in preview
177
    classTarget: '.story-wrapper'
178
  }
179
};
180
```
181

182
### Complete Configuration Example
183

184
```javascript
185
import { themes } from '@storybook/theming';
186

187
export const parameters = {
188
  darkMode: {
189
    // Initial theme
190
    current: 'light',
191
    
192
    // Custom themes
193
    dark: {
194
      ...themes.dark,
195
      appBg: '#0d1117',
196
      appContentBg: '#161b22',
197
      appBorderColor: '#30363d',
198
      textColor: '#f0f6fc',
199
      barTextColor: '#f0f6fc',
200
      barSelectedColor: '#58a6ff',
201
      barBg: '#161b22'
202
    },
203
    light: {
204
      ...themes.normal,
205
      appBg: '#ffffff',
206
      appContentBg: '#ffffff',
207
      appBorderColor: '#e1e4e8',
208
      textColor: '#24292f',
209
      barTextColor: '#24292f',
210
      barSelectedColor: '#0969da',
211
      barBg: '#f6f8fa'
212
    },
213
    
214
    // CSS class configuration
215
    darkClass: ['dark-mode', 'high-contrast'],
216
    lightClass: ['light-mode', 'standard-contrast'],
217
    classTarget: 'html',
218
    
219
    // Preview iframe styling
220
    stylePreview: true
221
  }
222
};
223
```
224

225
### Storage and Persistence
226

227
The addon automatically persists user theme preferences using localStorage with the key `'sb-addon-themes-3'`. This includes:
228

229
- Current theme selection
230
- Custom theme configurations
231
- User preference flags
232

233
**Storage Structure:**
234
```typescript
235
interface StoredData {
236
  current: 'light' | 'dark';
237
  dark: ThemeVars;
238
  light: ThemeVars;
239
  classTarget: string;
240
  darkClass: string | string[];
241
  lightClass: string | string[];
242
  stylePreview: boolean;
243
  userHasExplicitlySetTheTheme: boolean;
244
}
245
```