0
# Storybook React
1

2
Storybook React is the React renderer package for Storybook, a frontend workshop for building UI components and pages in isolation. It provides React-specific functionality including component mounting, prop extraction, TypeScript support, and integration with React DevTools. The package enables developers to create, test, and document React components with hot reloading, interactive controls, and comprehensive testing capabilities.
3

4
## Package Information
5

6
- **Package Name**: @storybook/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/react`
10

11
## Core Imports
12

13
```typescript
14
// Essential types for story creation
15
import type { Meta, StoryObj, StoryFn, Preview } from "@storybook/react";
16

17
// Decorator and configuration types
18
import type { Decorator, Loader, StoryContext } from "@storybook/react";
19

20
// Advanced preview configuration
21
import { __definePreview } from "@storybook/react";
22

23
// Portable stories for testing
24
import { composeStory, composeStories, setProjectAnnotations } from "@storybook/react";
25

26
// Experimental Playwright integration
27
import { createTest } from "@storybook/react/experimental-playwright";
28

29
// React renderer types (for advanced usage)
30
import type { ReactRenderer, ReactTypes, ReactParameters } from "@storybook/react";
31
```
32

33
For CommonJS:
34

35
```javascript
36
const { Meta, StoryObj, composeStory, composeStories } = require("@storybook/react");
37
```
38

39
**Dependencies:**
40

41
This package requires the following peer dependencies:
42
- `react` (^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta)
43
- `react-dom` (^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta)
44
- `storybook` (workspace:^)
45
- `typescript` (>= 4.9.x, optional)
46

47
## Basic Usage
48

49
```typescript
50
import type { Meta, StoryObj } from "@storybook/react";
51
import { Button } from "./Button";
52

53
// Define component metadata
54
const meta: Meta<typeof Button> = {
55
  title: "Example/Button",
56
  component: Button,
57
  parameters: {
58
    layout: "centered",
59
  },
60
  tags: ["autodocs"],
61
  argTypes: {
62
    backgroundColor: { control: "color" },
63
  },
64
};
65

66
export default meta;
67
type Story = StoryObj<typeof meta>;
68

69
// Define stories
70
export const Primary: Story = {
71
  args: {
72
    primary: true,
73
    label: "Button",
74
  },
75
};
76

77
export const Secondary: Story = {
78
  args: {
79
    label: "Button",
80
  },
81
};
82
```
83

84
## Architecture
85

86
Storybook React is built around several key components:
87

88
- **Type System**: Complete TypeScript definitions for React components, stories, and configurations
89
- **Portable Stories**: Stories can be reused outside Storybook for unit testing and other purposes
90
- **React Renderer**: Handles React-specific rendering including error boundaries and React DevTools integration
91
- **Preview System**: Configurable preview environment with decorators and parameters
92
- **CSF Support**: Component Story Format v2 and v3 with full type safety
93
- **Testing Integration**: Built-in compatibility with testing libraries and Playwright
94

95
## Capabilities
96

97
### Story Types & Metadata
98

99
Core TypeScript definitions for creating type-safe stories and component metadata. Essential for all Storybook React usage.
100

101
```typescript { .api }
102
type Meta<TCmpOrArgs = Args> = ComponentAnnotations<ReactRenderer, ComponentProps<TCmpOrArgs>>;
103

104
type StoryObj<TMetaOrCmpOrArgs = Args> = StoryAnnotations<ReactRenderer, TMetaOrCmpOrArgs>;
105

106
type StoryFn<TCmpOrArgs = Args> = AnnotatedStoryFn<ReactRenderer, ComponentProps<TCmpOrArgs>>;
107
```
108

109
[Story Types & Metadata](./story-types.md)
110

111
### Portable Stories
112

113
Functionality for using Storybook stories outside of Storybook, particularly useful for unit testing and component reuse.
114

115
```typescript { .api }
116
function setProjectAnnotations(
117
  projectAnnotations: NamedOrDefaultProjectAnnotations<any> | NamedOrDefaultProjectAnnotations<any>[]
118
): NormalizedProjectAnnotations<ReactRenderer>;
119

120
function composeStory<TArgs extends Args = Args>(
121
  story: StoryAnnotationsOrFn<ReactRenderer, TArgs>,
122
  componentAnnotations: Meta<TArgs | any>,
123
  projectAnnotations?: ProjectAnnotations<ReactRenderer>,
124
  exportsName?: string
125
): ComposedStoryFn<ReactRenderer, Partial<TArgs>>;
126

127
function composeStories<TModule extends Store_CSFExports<ReactRenderer, any>>(
128
  csfExports: TModule,
129
  projectAnnotations?: ProjectAnnotations<ReactRenderer>
130
): Omit<StoriesWithPartialProps<ReactRenderer, TModule>, keyof Store_CSFExports>;
131
```
132

133
[Portable Stories](./portable-stories.md)
134

135
### Preview Configuration
136

137
Advanced preview system for configuring the Storybook React environment, decorators, and rendering behavior.
138

139
```typescript { .api }
140
function __definePreview<Addons extends PreviewAddon<never>[]>(
141
  input: { addons: Addons } & ProjectAnnotations<ReactTypes & InferTypes<Addons>>
142
): ReactPreview<ReactTypes & InferTypes<Addons>>;
143

144
interface ReactPreview<T extends AddonTypes> extends Preview<ReactTypes & T> {
145
  meta<TArgs extends Args>(
146
    meta: ComponentAnnotations<ReactTypes & T, TArgs>
147
  ): ReactMeta<ReactTypes & T, TArgs>;
148
}
149
```
150

151
[Preview Configuration](./preview-configuration.md)
152

153
### React Renderer Types
154

155
Core React renderer interfaces and type definitions for handling React-specific functionality.
156

157
```typescript { .api }
158
interface ReactRenderer extends WebRenderer {
159
  component: ComponentType<this['T']>;
160
  storyResult: StoryFnReactReturnType;
161
  mount: (ui?: JSX.Element) => Promise<Canvas>;
162
}
163

164
interface ReactTypes extends ReactRenderer {
165
  parameters: ReactParameters;
166
}
167

168
interface ReactParameters {
169
  react?: {
170
    rsc?: boolean;
171
    rootOptions?: RootOptions;
172
  };
173
}
174
```
175

176
[React Renderer Types](./react-renderer.md)
177

178
### Testing Integration
179

180
Testing utilities and experimental Playwright integration for enhanced testing workflows.
181

182
```typescript { .api }
183
function createTest(): any;
184
```
185

186
[Testing Integration](./testing-integration.md)