0
# Preview Configuration
1

2
Advanced preview system for configuring the Storybook React environment, including decorators, parameters, and rendering behavior. The preview configuration enables type-safe story creation with addon integration and custom rendering logic.
3

4
## Type Dependencies
5

6
The preview configuration API depends on Storybook core and React types:
7

8
```typescript
9
// Main preview configuration export
10
import { __definePreview } from "@storybook/react";
11

12
// Core Storybook types
13
import type {
14
  Args,
15
  ProjectAnnotations,
16
  ComponentAnnotations,
17
  StoryAnnotations,
18
  DecoratorFunction,
19
  ArgsStoryFn,
20
  PreviewAddon,
21
  AddonTypes,
22
  Preview,
23
  Meta,
24
  Story,
25
  InferTypes
26
} from "storybook/internal/types";
27

28
// React types
29
import type { ComponentType } from "react";
30

31
// Utility types
32
import type { SetOptional, Simplify, UnionToIntersection } from "type-fest";
33

34
// React renderer types (see React Renderer Types documentation)
35
import type { ReactTypes, ReactRenderer } from "./react-renderer.md";
36

37
// Story types (see Story Types & Metadata documentation)
38
import type { AddMocks } from "./story-types.md#addmocks-type-helper";
39
```
40

41
## Capabilities
42

43
### Define Preview
44

45
Creates a strongly-typed preview configuration with addon support and React-specific functionality.
46

47
```typescript { .api }
48
/**
49
 * Defines a preview configuration with addon integration and type safety.
50
 * Combines React renderer annotations with custom addons and project configuration.
51
 * 
52
 * @param input - Configuration object containing addons and project annotations
53
 * @returns Strongly-typed ReactPreview instance with addon support
54
 */
55
function __definePreview<Addons extends PreviewAddon<never>[]>(
56
  input: { addons: Addons } & ProjectAnnotations<ReactTypes & InferTypes<Addons>>
57
): ReactPreview<ReactTypes & InferTypes<Addons>>;
58
```
59

60
**Usage Example:**
61

62
```typescript
63
import { __definePreview } from "@storybook/react";
64
import type { Preview } from "@storybook/react";
65

66
// Define preview with custom configuration
67
const preview = __definePreview({
68
  addons: [], // Custom addons would go here
69
  parameters: {
70
    actions: { argTypesRegex: "^on[A-Z].*" },
71
    controls: {
72
      matchers: {
73
        color: /(background|color)$/i,
74
        date: /Date$/,
75
      },
76
    },
77
    backgrounds: {
78
      default: "light",
79
      values: [
80
        { name: "light", value: "#ffffff" },
81
        { name: "dark", value: "#333333" },
82
      ],
83
    },
84
  },
85
  decorators: [
86
    (Story, context) => (
87
      <div className={`theme-${context.globals.theme}`}>
88
        <Story />
89
      </div>
90
    ),
91
  ],
92
});
93
```
94

95
### React Preview Interface
96

97
Extended preview interface that provides React-specific functionality and type-safe meta creation.
98

99
```typescript { .api }
100
/**
101
 * Extended preview interface for React with addon type inference.
102
 * Provides enhanced meta creation with React-specific typing and story composition.
103
 */
104
interface ReactPreview<T extends AddonTypes> extends Preview<ReactTypes & T> {
105
  /**
106
   * Creates component metadata with React-specific type safety and addon support.
107
   * Automatically configures story creation with proper component prop inference.
108
   */
109
  meta<
110
    TArgs extends Args,
111
    Decorators extends DecoratorFunction<ReactTypes & T, any>,
112
    TMetaArgs extends Partial<TArgs>,
113
  >(
114
    meta: {
115
      render?: ArgsStoryFn<ReactTypes & T, TArgs>;
116
      component?: ComponentType<TArgs>;
117
      decorators?: Decorators | Decorators[];
118
      args?: TMetaArgs;
119
    } & Omit<
120
      ComponentAnnotations<ReactTypes & T, TArgs>,
121
      'decorators' | 'component' | 'args' | 'render'
122
    >
123
  ): ReactMeta<ReactTypes & T, TArgs>;
124
}
125
```
126

127
**Usage Example:**
128

129
```typescript
130
const preview = __definePreview({
131
  addons: [],
132
  // ... other configuration
133
});
134

135
// Create type-safe meta using the preview
136
const buttonMeta = preview.meta({
137
  title: "Example/Button",
138
  component: Button,
139
  args: {
140
    primary: false,
141
    size: "medium",
142
  },
143
  argTypes: {
144
    size: {
145
      control: { type: "select" },
146
      options: ["small", "medium", "large"],
147
    },
148
  },
149
});
150
```
151

152
### React Meta Interface
153

154
Enhanced meta interface that provides React-specific story creation capabilities.
155

156
```typescript { .api }
157
/**
158
 * React-specific meta interface that extends standard Meta with React functionality.
159
 * Provides enhanced story creation with component inference and decorator support.
160
 */
161
interface ReactMeta<T extends ReactTypes, MetaInput extends ComponentAnnotations<T>>
162
  extends Meta<T, MetaInput> {
163
  /**
164
   * Creates a story with React-specific functionality and type safety.
165
   * Supports both functional and object-based story definitions.
166
   */
167
  story<
168
    TInput extends
169
      | (() => ReactTypes['storyResult'])
170
      | (StoryAnnotations<T, T['args']> & {
171
          render: () => ReactTypes['storyResult'];
172
        }),
173
  >(
174
    story?: TInput
175
  ): ReactStory<T, TInput extends () => ReactTypes['storyResult'] ? { render: TInput } : TInput>;
176

177
  /**
178
   * Creates a story with full configuration and type inference.
179
   * Handles optional args based on meta configuration.
180
   */
181
  story<
182
    TInput extends Simplify<
183
      StoryAnnotations<
184
        T,
185
        AddMocks<T['args'], MetaInput['args']>,
186
        SetOptional<T['args'], keyof T['args'] & keyof MetaInput['args']>
187
      >
188
    >,
189
  >(
190
    story?: TInput
191
  ): ReactStory<T, TInput>;
192
}
193
```
194

195
### React Story Interface
196

197
Enhanced story interface that provides a composable React component.
198

199
```typescript { .api }
200
/**
201
 * React-specific story interface that extends standard Story with React functionality.
202
 * Provides a Component property that can be rendered directly as a React component.
203
 */
204
interface ReactStory<T extends ReactTypes, TInput extends StoryAnnotations<T, T['args']>>
205
  extends Story<T, TInput> {
206
  /**
207
   * React component that can be rendered directly.
208
   * Automatically composed with story configuration and args.
209
   */
210
  Component: ComponentType<Partial<T['args']>>;
211
}
212
```
213

214
**Usage Example:**
215

216
```typescript
217
const meta = preview.meta({
218
  component: Button,
219
  args: { size: "medium" },
220
});
221

222
const primaryStory = meta.story({
223
  args: { primary: true },
224
});
225

226
// Use the Component property to render the story
227
function MyTest() {
228
  return (
229
    <div>
230
      <primaryStory.Component label="Test Button" />
231
    </div>
232
  );
233
}
234
```
235

236
### Decorator Args Type Helper
237

238
Type helper for inferring args from decorator functions.
239

240
```typescript { .api }
241
/**
242
 * Type helper that extracts and merges args from decorator functions.
243
 * Ensures proper type inference when multiple decorators provide args.
244
 */
245
type DecoratorsArgs<TRenderer extends Renderer, Decorators> = UnionToIntersection<
246
  Decorators extends DecoratorFunction<TRenderer, infer TArgs> ? TArgs : unknown
247
>;
248
```
249

250
## Advanced Configuration Patterns
251

252
**Custom Decorator with Args:**
253

254
```typescript
255
import type { Decorator } from "@storybook/react";
256

257
const withTheme: Decorator<{ theme?: string }> = (Story, context) => {
258
  const theme = context.args.theme || context.parameters.theme || "light";
259
  return (
260
    <div className={`theme-${theme}`}>
261
      <Story />
262
    </div>
263
  );
264
};
265

266
const preview = __definePreview({
267
  addons: [],
268
  decorators: [withTheme],
269
  parameters: {
270
    theme: "light",
271
  },
272
});
273
```
274

275
**Preview with Global Types:**
276

277
```typescript
278
import type { Preview } from "@storybook/react";
279

280
// Define global types for your project
281
declare module "@storybook/react" {
282
  interface Parameters {
283
    myCustomParameter?: {
284
      option1: boolean;
285
      option2: string;
286
    };
287
  }
288
}
289

290
const preview: Preview = {
291
  parameters: {
292
    myCustomParameter: {
293
      option1: true,
294
      option2: "default",
295
    },
296
  },
297
};
298
```
299

300
**React Server Components Configuration:**
301

302
```typescript
303
const preview = __definePreview({
304
  addons: [],
305
  parameters: {
306
    react: {
307
      rsc: true, // Enable React Server Components
308
      rootOptions: {
309
        onRecoverableError: (error) => {
310
          console.warn("Recoverable error:", error);
311
        },
312
      },
313
    },
314
  },
315
});
316
```
317

318
## Internal Configuration
319

320
The preview system internally includes several React-specific annotations:
321

322
- **reactAnnotations**: Core React rendering functionality
323
- **reactArgTypesAnnotations**: Automatic argTypes inference for React props
324
- **reactDocsAnnotations**: Documentation generation for React components
325

326
These are automatically included in the preview configuration and provide the foundation for React-specific Storybook functionality.