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
```