0
# React Renderer Types
1

2
Core React renderer interfaces and type definitions that handle React-specific functionality in Storybook. These types define how React components are rendered, mounted, and configured within the Storybook environment.
3

4
## Type Dependencies
5

6
The React renderer types depend on Storybook core and React DOM types:
7

8
```typescript
9
// Core exports from @storybook/react
10
export type { ReactRenderer, ReactTypes, ReactParameters } from "@storybook/react";
11

12
// React types
13
import type { ComponentType, JSX } from "react";
14
import type { RootOptions } from "react-dom/client";
15

16
// Core Storybook types
17
import type {
18
  WebRenderer,
19
  Canvas,
20
  RenderContext,
21
  StoryContext as GenericStoryContext
22
} from "storybook/internal/types";
23
```
24

25
## Capabilities
26

27
### React Renderer Interface
28

29
Core interface that defines the React renderer's capabilities and type system.
30

31
```typescript { .api }
32
/**
33
 * Core React renderer interface that extends WebRenderer with React-specific functionality.
34
 * Defines how React components are handled within Storybook.
35
 */
36
interface ReactRenderer extends WebRenderer {
37
  /** The React component type being rendered */
38
  component: ComponentType<this['T']>;
39
  /** The expected return type from story functions (JSX.Element) */
40
  storyResult: StoryFnReactReturnType;
41
  /** Function to mount React elements for testing */
42
  mount: (ui?: JSX.Element) => Promise<Canvas>;
43
}
44
```
45

46
The ReactRenderer interface provides the foundation for all React-specific functionality in Storybook, ensuring type safety and proper component handling.
47

48
### React Types Interface
49

50
Extended type system that includes React-specific parameters and configuration.
51

52
```typescript { .api }
53
/**
54
 * Extended React type system that includes renderer capabilities and React-specific parameters.
55
 * Used throughout the React renderer for type inference and configuration.
56
 */
57
interface ReactTypes extends ReactRenderer {
58
  /** React-specific parameters for story configuration */
59
  parameters: ReactParameters;
60
}
61
```
62

63
### React Parameters Interface
64

65
Configuration interface for React-specific parameters and options.
66

67
```typescript { .api }
68
/**
69
 * React-specific parameters interface for configuring React behavior in stories.
70
 * Includes options for React Server Components and React DOM configuration.
71
 */
72
interface ReactParameters {
73
  /** React renderer configuration */
74
  react?: {
75
    /**
76
     * Whether to enable React Server Components (RSC)
77
     * Requires React >= 18.3 for proper functionality
78
     * 
79
     * @see https://storybook.js.org/docs/get-started/frameworks/nextjs#react-server-components-rsc
80
     */
81
    rsc?: boolean;
82
    /** Options passed to React root creation (React 18+) */
83
    rootOptions?: RootOptions;
84
  };
85
}
86
```
87

88
**Usage Example:**
89

90
```typescript
91
import type { Meta, StoryObj } from "@storybook/react";
92
import { ServerComponent } from "./ServerComponent";
93

94
const meta: Meta<typeof ServerComponent> = {
95
  title: "Example/ServerComponent",
96
  component: ServerComponent,
97
  parameters: {
98
    react: {
99
      rsc: true, // Enable React Server Components
100
      rootOptions: {
101
        onRecoverableError: (error) => {
102
          console.warn("RSC recoverable error:", error);
103
        },
104
      },
105
    },
106
  },
107
};
108

109
export default meta;
110
type Story = StoryObj<typeof meta>;
111

112
export const Default: Story = {};
113
```
114

115
### Story Function Return Type
116

117
Type definition for the expected return value from React story functions.
118

119
```typescript { .api }
120
/**
121
 * The expected return type from React story functions.
122
 * All React stories must return JSX elements.
123
 */
124
type StoryFnReactReturnType = JSX.Element;
125
```
126

127
**Usage Example:**
128

129
```typescript
130
import type { StoryFn } from "@storybook/react";
131
import { Button } from "./Button";
132

133
// Story function must return JSX.Element
134
const Primary: StoryFn<typeof Button> = (args): StoryFnReactReturnType => {
135
  return <Button {...args} />;
136
};
137
```
138

139
### Show Error Args Interface
140

141
Interface for error display configuration within the React renderer.
142

143
```typescript { .api }
144
/**
145
 * Configuration interface for displaying errors in the React renderer.
146
 * Used by error boundaries and error handling mechanisms.
147
 */
148
interface ShowErrorArgs {
149
  /** The main error title to display */
150
  title: string;
151
  /** Detailed error description or message */
152
  description: string;
153
}
154
```
155

156
This interface is used internally by the React renderer's error boundary system to display meaningful error messages when stories fail to render.
157

158
### Re-exported Core Types
159

160
Essential types from Storybook core that are commonly used with React renderer.
161

162
```typescript { .api }
163
/**
164
 * Render context type providing access to story execution context.
165
 * Contains story metadata, canvas elements, and rendering functions.
166
 */
167
type RenderContext = RenderContext<ReactRenderer>;
168

169
/**
170
 * Story context type providing access to story state and configuration.
171
 * Available in decorators, loaders, and render functions.
172
 */
173
type StoryContext = StoryContext<ReactRenderer>;
174
```
175

176
## Advanced Usage Patterns
177

178
### Custom Mount Function
179

180
```typescript
181
import type { ReactRenderer } from "@storybook/react";
182

183
const customMount: ReactRenderer['mount'] = (context) => async (ui) => {
184
  if (ui != null) {
185
    context.originalStoryFn = () => ui;
186
  }
187
  
188
  // Custom mounting logic
189
  await context.renderToCanvas();
190
  
191
  // Return the canvas for testing
192
  return context.canvas;
193
};
194
```
195

196
### React 18+ Root Options Configuration
197

198
```typescript
199
import type { Meta } from "@storybook/react";
200
import type { RootOptions } from "react-dom/client";
201

202
const rootOptions: RootOptions = {
203
  onRecoverableError: (error, errorInfo) => {
204
    console.error("React recoverable error:", error, errorInfo);
205
  },
206
  identifierPrefix: "storybook-",
207
};
208

209
const meta: Meta = {
210
  parameters: {
211
    react: {
212
      rootOptions,
213
    },
214
  },
215
};
216
```
217

218
### Error Boundary Integration
219

220
The React renderer automatically includes error boundaries for story rendering:
221

222
```typescript
223
// Internal error boundary implementation
224
class ErrorBoundary extends React.Component<{
225
  showException: (err: Error) => void;
226
  showMain: () => void;
227
  children?: React.ReactNode;
228
}> {
229
  state = { hasError: false };
230

231
  static getDerivedStateFromError() {
232
    return { hasError: true };
233
  }
234

235
  componentDidCatch(err: Error) {
236
    const { showException } = this.props;
237
    showException(err);
238
  }
239

240
  render() {
241
    const { hasError } = this.state;
242
    const { children } = this.props;
243
    return hasError ? null : children;
244
  }
245
}
246
```
247

248
### React Server Components Setup
249

250
```typescript
251
import type { Preview } from "@storybook/react";
252

253
const preview: Preview = {
254
  parameters: {
255
    react: {
256
      rsc: true,
257
    },
258
  },
259
  decorators: [
260
    (Story, context) => {
261
      // RSC requires React.Suspense wrapper
262
      if (context.parameters?.react?.rsc) {
263
        return (
264
          <React.Suspense fallback={<div>Loading...</div>}>
265
            <Story />
266
          </React.Suspense>
267
        );
268
      }
269
      return <Story />;
270
    },
271
  ],
272
};
273

274
export default preview;
275
```
276

277
## Type System Integration
278

279
The React renderer types integrate seamlessly with the broader Storybook type system:
280

281
- **ReactRenderer** extends **WebRenderer** for browser compatibility
282
- **ReactTypes** combines renderer and parameter types for full functionality
283
- **ReactParameters** extends the global Parameters interface for React-specific options
284
- All types maintain compatibility with Storybook's CSF (Component Story Format) specification
285

286
These types ensure that React components, stories, and configurations are properly typed throughout the Storybook development experience.