0
# Storybook Preview API
1
2
Storybook Preview API is the core interface for building UI components in isolation within the Storybook preview environment. It provides React-like hooks for state management, decorators for story enhancement, CSF (Component Story Format) utilities for story composition, and simulation tools for testing scenarios.
3
4
## Package Information
5
6
- **Package Name**: @storybook/preview-api
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @storybook/preview-api` (requires Storybook ^8.2.0)
10
11
## Core Imports
12
13
For ESM:
14
15
```typescript
16
import {
17
useArgs,
18
useGlobals,
19
makeDecorator,
20
composeStory,
21
StoryStore,
22
DocsContext,
23
definePreview,
24
experimental_useUniversalStore,
25
simulatePageLoad,
26
simulateDOMContentLoaded
27
} from "@storybook/preview-api";
28
```
29
30
For CommonJS:
31
32
```javascript
33
const {
34
useArgs,
35
useGlobals,
36
makeDecorator,
37
composeStory,
38
StoryStore,
39
DocsContext,
40
definePreview,
41
experimental_useUniversalStore,
42
simulatePageLoad,
43
simulateDOMContentLoaded
44
} = require("@storybook/preview-api");
45
```
46
47
## Basic Usage
48
49
```typescript
50
import { useArgs, useGlobals, composeStory } from "@storybook/preview-api";
51
52
// Using hooks in story decorators
53
export const MyDecorator = (Story, context) => {
54
const [args, updateArgs] = useArgs();
55
const [globals] = useGlobals();
56
57
return <Story />;
58
};
59
60
// Composing portable stories
61
import type { Meta, StoryObj } from '@storybook/react';
62
import * as ButtonStories from './Button.stories';
63
64
const meta: Meta<typeof Button> = ButtonStories.default;
65
const Primary = composeStory(ButtonStories.Primary, meta);
66
67
// Usage in tests
68
test('Primary button renders correctly', () => {
69
render(<Primary />);
70
});
71
```
72
73
## Architecture
74
75
The Storybook Preview API is built around several key architectural components:
76
77
- **Hooks System**: React-like hooks providing state management and lifecycle methods for stories
78
- **Decorator System**: Powerful middleware pattern for story enhancement and composition
79
- **CSF Engine**: Component Story Format processing and normalization utilities
80
- **Store Management**: Centralized state management for stories, args, and global parameters
81
- **Preview Environment**: Web-based preview system with story selection and rendering
82
- **Simulation Tools**: Testing utilities for DOM manipulation and page lifecycle simulation
83
84
## Capabilities
85
86
### Hooks API
87
88
React-like hooks for state management, lifecycle methods, and communication within the Storybook preview environment. Essential for building interactive stories and custom addons.
89
90
```typescript { .api }
91
function useArgs<TArgs>(): [TArgs, (newArgs: Partial<TArgs>) => void, (argNames?: (keyof TArgs)[]) => void];
92
function useGlobals(): [Args, (newGlobals: Args) => void];
93
function useStoryContext<TRenderer>(): StoryContext<TRenderer>;
94
function useParameter<S>(parameterKey: string, defaultValue?: S): S | undefined;
95
```
96
97
[Hooks API](./hooks.md)
98
99
### Decorators
100
101
System for creating reusable story enhancements and middleware. Decorators wrap stories to provide additional functionality like theming, layouts, or data providers.
102
103
```typescript { .api }
104
function makeDecorator(options: MakeDecoratorOptions): MakeDecoratorResult;
105
106
interface MakeDecoratorOptions {
107
name: string;
108
parameterName: string;
109
skipIfNoParametersOrOptions?: boolean;
110
wrapper: (storyFn: StoryFn, context: StoryContext) => any;
111
}
112
```
113
114
[Decorators](./decorators.md)
115
116
### Story Composition & CSF
117
118
Utilities for creating portable stories, composing story configurations, and working with Component Story Format. Perfect for testing, documentation generation, and cross-environment story usage.
119
120
```typescript { .api }
121
function composeStory<TRenderer>(
122
storyAnnotations: StoryAnnotations<TRenderer, any>,
123
componentAnnotations: ComponentAnnotations<TRenderer, any>,
124
projectAnnotations?: ProjectAnnotations<TRenderer>,
125
defaultConfig?: ProjectAnnotations<TRenderer>,
126
exportsName?: string
127
): ComposedStoryFn<TRenderer, any>;
128
129
function composeStories<TModule>(
130
storiesImport: TModule,
131
globalConfig: ProjectAnnotations<any>,
132
composeStoryFn?: Function
133
): Record<string, ComposedStoryFn<any, any>>;
134
```
135
136
[Story Composition](./story-composition.md)
137
138
### Story Store & Management
139
140
Central story management system providing story loading, caching, args management, and context creation. Core infrastructure for Storybook's preview environment.
141
142
```typescript { .api }
143
class StoryStore<TRenderer> {
144
storyIndex: StoryIndex;
145
projectAnnotations: ProjectAnnotations<TRenderer>;
146
userGlobals: Args;
147
args: ArgsStore;
148
hooks: HooksContext<TRenderer>;
149
}
150
151
function setProjectAnnotations<TRenderer>(projectAnnotations: ProjectAnnotations<TRenderer>): void;
152
function setDefaultProjectAnnotations<TRenderer>(defaultProjectAnnotations: ProjectAnnotations<TRenderer>): void;
153
```
154
155
[Story Store](./story-store.md)
156
157
### Preview System
158
159
Web-based preview environment with story selection, rendering, and URL-based state management. Handles the complete story rendering lifecycle in browser environments.
160
161
```typescript { .api }
162
class PreviewWeb<TRenderer> {
163
constructor(args: PreviewWebArgs<TRenderer>);
164
ready(): Promise<void>;
165
render(renderOptions: RenderOptions): Promise<void>;
166
}
167
168
class Preview<TRenderer> {
169
constructor(imports: PreviewArgs<TRenderer>);
170
ready(): Promise<void>;
171
}
172
```
173
174
[Preview System](./preview-system.md)
175
176
### Testing & Simulation
177
178
Tools for simulating DOM events, page lifecycle, and creating test utilities. Essential for testing stories and addons in various environments.
179
180
```typescript { .api }
181
function simulatePageLoad(container: Element): void;
182
function simulateDOMContentLoaded(): void;
183
function createPlaywrightTest<TFixture>(baseTest: TFixture): any;
184
```
185
186
[Testing & Simulation](./testing-simulation.md)
187
188
### Docs Context & Documentation
189
190
Context provider for documentation rendering and metadata access. Provides documentation-specific functionality for Storybook's docs pages.
191
192
```typescript { .api }
193
class DocsContext {
194
constructor(channel: Channel, store: StoryStore, renderStoryToElement: Function, collectionId?: string);
195
componentStories(): Story[];
196
storyById(id?: string): Story;
197
getStoryContext(story: Story): StoryContext;
198
}
199
```
200
201
### Preview Configuration
202
203
Utilities for configuring the Storybook preview environment with global settings and annotations.
204
205
```typescript { .api }
206
function definePreview(preview: ProjectAnnotations): ProjectAnnotations;
207
```
208
209
### Experimental Universal Store
210
211
Experimental state management system for cross-environment story state synchronization.
212
213
```typescript { .api }
214
function experimental_useUniversalStore<T>(key: string, initialValue?: T): [T, (value: T) => void];
215
216
class experimental_UniversalStore {
217
get<T>(key: string): T | undefined;
218
set<T>(key: string, value: T): void;
219
subscribe<T>(key: string, listener: (value: T) => void): () => void;
220
}
221
222
class experimental_MockUniversalStore extends experimental_UniversalStore {
223
constructor(initialState?: Record<string, any>);
224
reset(): void;
225
}
226
```
227
228
## Types & Core Interfaces
229
230
```typescript { .api }
231
interface Args {
232
[key: string]: any;
233
}
234
235
interface StoryContext<TRenderer = any> {
236
id: string;
237
name: string;
238
title: string;
239
parameters: Parameters;
240
args: Args;
241
argTypes: ArgTypes;
242
globals: Args;
243
hooks: HooksContext<TRenderer>;
244
}
245
246
interface ComposedStoryFn<TRenderer = any, TArgs = any> {
247
(args?: Partial<TArgs>): any;
248
storyName?: string;
249
args?: TArgs;
250
parameters?: Parameters;
251
argTypes?: ArgTypes;
252
}
253
254
interface ProjectAnnotations<TRenderer = any> {
255
parameters?: Parameters;
256
decorators?: DecoratorFunction<TRenderer>[];
257
args?: Args;
258
argTypes?: ArgTypes;
259
globals?: Args;
260
globalTypes?: GlobalTypes;
261
}
262
263
interface GlobalTypes {
264
[key: string]: {
265
name?: string;
266
description?: string;
267
defaultValue?: any;
268
toolbar?: {
269
title?: string;
270
icon?: string;
271
items?: Array<{ value: any; title: string; icon?: string }>;
272
showName?: boolean;
273
dynamicTitle?: boolean;
274
};
275
control?: {
276
type: 'boolean' | 'text' | 'number' | 'range' | 'object' | 'file' | 'radio' | 'inline-radio' | 'check' | 'inline-check' | 'select' | 'multi-select' | 'color' | 'date';
277
[key: string]: any;
278
};
279
};
280
}
281
282
interface ArgTypes {
283
[key: string]: ArgType;
284
}
285
286
interface ArgType {
287
name?: string;
288
description?: string;
289
defaultValue?: any;
290
type?: {
291
name: 'boolean' | 'string' | 'number' | 'object' | 'array' | 'function';
292
value?: any;
293
required?: boolean;
294
};
295
control?: {
296
type: 'boolean' | 'text' | 'number' | 'range' | 'object' | 'file' | 'radio' | 'inline-radio' | 'check' | 'inline-check' | 'select' | 'multi-select' | 'color' | 'date';
297
[key: string]: any;
298
};
299
table?: {
300
type?: { summary: string; detail?: string };
301
defaultValue?: { summary: string; detail?: string };
302
disable?: boolean;
303
};
304
}
305
306
interface Parameters {
307
[key: string]: any;
308
}
309
310
interface Channel {
311
emit(eventId: string, ...args: any[]): void;
312
on(eventId: string, listener: Function): void;
313
off(eventId: string, listener: Function): void;
314
once(eventId: string, listener: Function): void;
315
addListener(eventId: string, listener: Function): void;
316
removeListener(eventId: string, listener: Function): void;
317
removeAllListeners(eventId?: string): void;
318
}
319
```