0
# Storybook Dark Mode
1
2
Storybook Dark Mode is a Storybook addon that enables users to toggle between light and dark mode themes within the Storybook interface. It provides comprehensive theme customization through configuration parameters, React hooks for component integration, and programmatic theme control with localStorage persistence.
3
4
## Package Information
5
6
- **Package Name**: storybook-dark-mode
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev storybook-dark-mode`
10
11
## Core Imports
12
13
```typescript
14
import { useDarkMode } from 'storybook-dark-mode';
15
```
16
17
For event-based integration:
18
19
```typescript
20
import {
21
DARK_MODE_EVENT_NAME,
22
UPDATE_DARK_MODE_EVENT_NAME
23
} from 'storybook-dark-mode';
24
```
25
26
For advanced/internal APIs:
27
28
```typescript
29
import { store, updateStore, prefersDark } from 'storybook-dark-mode';
30
```
31
32
## Basic Usage
33
34
### 1. Add to Storybook Configuration
35
36
Add to `.storybook/main.js`:
37
38
```javascript
39
module.exports = {
40
addons: ['storybook-dark-mode']
41
};
42
```
43
44
### 2. Configure Themes (Optional)
45
46
Configure themes in `.storybook/preview.js`:
47
48
```javascript
49
import { themes } from '@storybook/theming';
50
51
export const parameters = {
52
darkMode: {
53
// Override the default dark theme
54
dark: { ...themes.dark, appBg: 'black' },
55
// Override the default light theme
56
light: { ...themes.normal, appBg: 'red' },
57
// Set the initial theme
58
current: 'light'
59
}
60
};
61
```
62
63
### 3. React Integration
64
65
Use the hook to integrate with your components:
66
67
```typescript
68
import React from 'react';
69
import { useDarkMode } from 'storybook-dark-mode';
70
71
function ThemeWrapper({ children }) {
72
const isDark = useDarkMode();
73
74
return (
75
<div className={isDark ? 'dark-theme' : 'light-theme'}>
76
{children}
77
</div>
78
);
79
}
80
```
81
82
## Architecture
83
84
Storybook Dark Mode is built around several key components:
85
86
- **Addon Integration**: Automatic registration with Storybook's addon system via preset configuration
87
- **Theme Management**: Centralized theme storage and persistence using localStorage
88
- **Event System**: Channel-based communication for theme state synchronization across Storybook
89
- **React Integration**: Hook-based API for component-level theme awareness
90
- **CSS Class Management**: Automatic application of theme classes to manager and preview iframes
91
- **OS Preference Detection**: Automatic theme detection based on user's system preferences
92
93
## Capabilities
94
95
### React Hook Integration
96
97
React hook for accessing current theme state within Storybook stories and components.
98
99
```typescript { .api }
100
function useDarkMode(): boolean;
101
```
102
103
[React Integration](./react-integration.md)
104
105
### Configuration System
106
107
Comprehensive configuration options for customizing themes, CSS classes, and behavior through Storybook parameters.
108
109
```typescript { .api }
110
type DarkModeParameters = Partial<DarkModeStore>;
111
```
112
113
[Configuration](./configuration.md)
114
115
### Event-Based Theme Control
116
117
Event system for manual theme control and integration with custom components.
118
119
```typescript { .api }
120
const DARK_MODE_EVENT_NAME: 'DARK_MODE';
121
const UPDATE_DARK_MODE_EVENT_NAME: 'UPDATE_DARK_MODE';
122
```
123
124
[Event System](./event-system.md)
125
126
### Internal APIs
127
128
Advanced APIs for low-level theme management, store functions, and OS preference detection.
129
130
```typescript { .api }
131
function store(userTheme?: Partial<DarkModeStore>): DarkModeStore;
132
function updateStore(newStore: DarkModeStore): void;
133
const prefersDark: MediaQueryList;
134
```
135
136
[Internal APIs](./internal-apis.md)
137
138
## Types
139
140
```typescript { .api }
141
type Mode = 'light' | 'dark';
142
143
interface DarkModeStore {
144
/** CSS selector for preview iframe target element */
145
classTarget: string;
146
/** Current active theme mode */
147
current: Mode;
148
/** Dark theme configuration object */
149
dark: ThemeVars;
150
/** CSS class(es) applied in dark mode */
151
darkClass: string | string[];
152
/** Light theme configuration object */
153
light: ThemeVars;
154
/** CSS class(es) applied in light mode */
155
lightClass: string | string[];
156
/** Whether to apply theme classes to preview iframe */
157
stylePreview: boolean;
158
/** Whether user has manually set a theme preference */
159
userHasExplicitlySetTheTheme: boolean;
160
}
161
162
/**
163
* Storybook theme configuration object (from @storybook/theming)
164
* Used to customize the appearance of the Storybook UI
165
*/
166
interface ThemeVars {
167
/** Main application background color */
168
appBg?: string;
169
/** Content area background color */
170
appContentBg?: string;
171
/** Border color for UI elements */
172
appBorderColor?: string;
173
/** Border radius for UI elements */
174
appBorderRadius?: number;
175
/** Base font family */
176
fontBase?: string;
177
/** Code/monospace font family */
178
fontCode?: string;
179
/** Primary text color */
180
textColor?: string;
181
/** Toolbar text color */
182
barTextColor?: string;
183
/** Selected toolbar item color */
184
barSelectedColor?: string;
185
/** Toolbar background color */
186
barBg?: string;
187
/** Input field background color */
188
inputBg?: string;
189
/** Input field border color */
190
inputBorder?: string;
191
/** Input field text color */
192
inputTextColor?: string;
193
/** Input field border radius */
194
inputBorderRadius?: number;
195
/** Brand title text */
196
brandTitle?: string;
197
/** Brand URL for logo/title links */
198
brandUrl?: string;
199
/** Brand image/logo URL */
200
brandImage?: string;
201
/** Brand target attribute for links */
202
brandTarget?: string;
203
/** Color palette */
204
colorPrimary?: string;
205
colorSecondary?: string;
206
/** Additional theme properties as defined by Storybook theming */
207
[key: string]: any;
208
}
209
```