0
# React Components and Hooks
1
2
Story components, context providers, navigation hooks, and built-in UI components for creating interactive and comprehensive component documentation.
3
4
## Capabilities
5
6
### Core Story Components
7
8
Essential components for defining and organizing stories within your component documentation.
9
10
```typescript { .api }
11
/**
12
* Component wrapper for individual stories
13
*/
14
const Story: React.FC<any>;
15
16
/**
17
* Component for story metadata and configuration
18
*/
19
const Meta: React.FC<any>;
20
21
/**
22
* Component for adding descriptions to stories
23
*/
24
const Description: React.FC<any>;
25
```
26
27
**Usage Examples:**
28
29
```typescript
30
import { Story, Meta, Description } from "@ladle/react";
31
32
// Basic story usage
33
export const BasicButton: Story = (args) => <Button {...args} />;
34
35
// Story with metadata
36
export const DocumentedButton: Story = (args) => (
37
<>
38
<Meta title="Button Examples" />
39
<Description>This is a documented button component</Description>
40
<Button {...args} />
41
</>
42
);
43
```
44
45
### Context and State Management
46
47
Access to Ladle's global state and dispatch functions for advanced story interactions.
48
49
```typescript { .api }
50
/**
51
* Hook to access Ladle's global state and dispatch function
52
* @returns Object containing globalState and dispatch
53
*/
54
function useLadleContext(): {
55
globalState: GlobalState;
56
dispatch: React.Dispatch<GlobalAction>;
57
};
58
59
interface GlobalState {
60
mode: ModeState; // "full" | "preview"
61
theme: ThemeState; // "light" | "dark" | "auto"
62
action: ActionState; // Action panel state
63
story: string; // Current story identifier
64
rtl: boolean; // Right-to-left text direction
65
source: boolean; // Source code visibility
66
control: ControlState; // Controls panel state
67
controlInitialized: boolean;
68
width: number; // Viewport width
69
hotkeys: boolean; // Hotkeys enabled state
70
}
71
72
type GlobalAction =
73
| { type: "UpdateAll"; payload: Partial<GlobalState> }
74
| { type: "UpdateMode"; payload: ModeState }
75
| { type: "UpdateTheme"; payload: ThemeState }
76
// ... other action types
77
```
78
79
**Usage Examples:**
80
81
```typescript
82
import { useLadleContext } from "@ladle/react";
83
84
function MyCustomStory() {
85
const { globalState, dispatch } = useLadleContext();
86
87
const toggleTheme = () => {
88
dispatch({
89
type: "UpdateTheme",
90
payload: globalState.theme === "light" ? "dark" : "light"
91
});
92
};
93
94
return (
95
<div>
96
<p>Current theme: {globalState.theme}</p>
97
<button onClick={toggleTheme}>Toggle Theme</button>
98
</div>
99
);
100
}
101
```
102
103
### Navigation Functions
104
105
Functions for programmatic navigation and action logging within stories.
106
107
```typescript { .api }
108
/**
109
* Function to create navigation handlers for specific stories
110
* @param value - Story identifier to navigate to
111
* @returns Click handler function for navigation
112
*/
113
function linkTo(value: string): () => void;
114
115
/**
116
* Function to create action handlers for logging events
117
* @param name - Name of the action for logging
118
* @returns Event handler function that logs the action
119
*/
120
function action(name: string): (event?: any) => void;
121
122
/**
123
* Hook for programmatic navigation (deprecated, use linkTo instead)
124
* @returns Navigation function
125
* @deprecated Use linkTo instead
126
*/
127
function useLink(): (value: string) => void;
128
```
129
130
**Usage Examples:**
131
132
```typescript
133
import { linkTo, action } from "@ladle/react";
134
135
function NavigationExample() {
136
const goToButton = linkTo("components-button--primary");
137
const logClick = action("button-clicked");
138
139
return (
140
<div>
141
<button onClick={goToButton}>
142
Go to Button Story
143
</button>
144
<button onClick={logClick}>
145
Log Action
146
</button>
147
</div>
148
);
149
}
150
```
151
152
### Built-in UI Components
153
154
Pre-styled UI components available in the `ui` namespace for consistent story interfaces.
155
156
```typescript { .api }
157
import { ui } from "@ladle/react";
158
159
/**
160
* Styled button component
161
*/
162
const ui.Button: React.FC<{
163
children: React.ReactNode;
164
onClick: React.MouseEventHandler<HTMLButtonElement>;
165
style?: React.CSSProperties;
166
"aria-label"?: string;
167
}>;
168
169
/**
170
* Styled link component
171
*/
172
const ui.Link: React.FC<{
173
href: string;
174
children: React.ReactNode;
175
style?: React.CSSProperties;
176
}>;
177
178
/**
179
* Styled code display component
180
*/
181
const ui.Code: React.FC<{
182
children: React.ReactNode;
183
}>;
184
185
/**
186
* Modal dialog component with overlay
187
*/
188
const ui.Modal: React.FC<{
189
children: React.ReactNode;
190
close: () => void;
191
isOpen: boolean;
192
label?: string;
193
maxWidth?: string;
194
}>;
195
```
196
197
**Usage Examples:**
198
199
```typescript
200
import { ui } from "@ladle/react";
201
202
function UIComponentsExample() {
203
const [isModalOpen, setIsModalOpen] = useState(false);
204
205
return (
206
<div>
207
<ui.Button onClick={() => setIsModalOpen(true)}>
208
Open Modal
209
</ui.Button>
210
211
<ui.Link href="https://example.com">
212
External Link
213
</ui.Link>
214
215
<ui.Code>
216
const code = "example";
217
</ui.Code>
218
219
<ui.Modal
220
isOpen={isModalOpen}
221
close={() => setIsModalOpen(false)}
222
label="Example Modal"
223
maxWidth="500px"
224
>
225
<p>Modal content goes here</p>
226
</ui.Modal>
227
</div>
228
);
229
}
230
```
231
232
### Dialog Components
233
234
Dialog primitives for building custom modal interfaces.
235
236
```typescript { .api }
237
import { dialog } from "@ladle/react";
238
239
/**
240
* Dialog overlay component for modal backgrounds
241
*/
242
const dialog.DialogOverlay: React.FC;
243
244
/**
245
* Dialog content container component
246
*/
247
const dialog.DialogContent: React.FC;
248
```
249
250
**Usage Examples:**
251
252
```typescript
253
import { dialog } from "@ladle/react";
254
255
function CustomDialog({ isOpen, onClose, children }) {
256
if (!isOpen) return null;
257
258
return (
259
<dialog.DialogOverlay>
260
<dialog.DialogContent>
261
<button onClick={onClose}>Close</button>
262
{children}
263
</dialog.DialogContent>
264
</dialog.DialogOverlay>
265
);
266
}
267
```
268
269
### Icon Components
270
271
SVG icon components for building custom interfaces and controls.
272
273
```typescript { .api }
274
import { icons } from "@ladle/react";
275
276
// Basic icons
277
const icons.Close: React.FC; // Close/X icon
278
const icons.Ladle: React.FC; // Ladle logo
279
const icons.Rtl: React.FC; // RTL direction icon
280
const icons.Preview: React.FC; // Preview mode icon
281
const icons.Bulb: React.FC; // Theme switching icon
282
const icons.Page: React.FC; // Page/document icon
283
const icons.Right: React.FC; // Right arrow icon
284
const icons.Controls: React.FC; // Controls panel icon
285
const icons.Source: React.FC; // Source code icon
286
const icons.A11y: React.FC; // Accessibility icon
287
const icons.Width: React.FC; // Width adjustment icon
288
const icons.Action: React.FC; // Action logging icon
289
290
// Icons with props
291
const icons.Down: React.FC<{
292
rotate?: boolean; // Rotate the arrow icon
293
}>;
294
295
// Special icons with side effects
296
const icons.Ring: React.FC; // Loading ring with animations
297
```
298
299
**Usage Examples:**
300
301
```typescript
302
import { icons } from "@ladle/react";
303
304
function CustomToolbar() {
305
const [expanded, setExpanded] = useState(false);
306
307
return (
308
<div>
309
<button onClick={() => setExpanded(!expanded)}>
310
<icons.Down rotate={expanded} />
311
Menu
312
</button>
313
314
{expanded && (
315
<div>
316
<icons.Controls /> Controls
317
<icons.Source /> Source
318
<icons.A11y /> Accessibility
319
</div>
320
)}
321
</div>
322
);
323
}
324
```
325
326
### MSW Integration
327
328
Mock Service Worker integration for API mocking in stories.
329
330
```typescript { .api }
331
import { msw } from "@ladle/react";
332
333
/**
334
* Complete MSW library re-export for API mocking
335
* Includes all MSW functionality for browser mocking
336
*/
337
const msw: typeof import("msw");
338
```
339
340
**Usage Examples:**
341
342
```typescript
343
import { msw } from "@ladle/react";
344
import type { Story } from "@ladle/react";
345
346
const MyComponent: Story = () => <ComponentThatMakesAPICall />;
347
348
// Add MSW handlers to story
349
MyComponent.msw = [
350
msw.http.get("/api/users", ({ request, params, cookies }) => {
351
return HttpResponse.json([
352
{ id: 1, name: "John Doe" },
353
{ id: 2, name: "Jane Smith" }
354
]);
355
})
356
];
357
```
358
359
### MDX Support
360
361
MDX component integration for rich documentation within stories.
362
363
```typescript { .api }
364
/**
365
* Hook for MDX component mapping from @mdx-js/react
366
*/
367
const useMDXComponents: typeof import("@mdx-js/react").useMDXComponents;
368
```
369
370
**Usage Examples:**
371
372
```typescript
373
import { useMDXComponents } from "@ladle/react";
374
375
function MDXStory() {
376
const components = useMDXComponents({
377
h1: (props) => <h1 style={{ color: "blue" }} {...props} />,
378
code: (props) => <code style={{ background: "#f0f0f0" }} {...props} />
379
});
380
381
// Use components in MDX context
382
return <div>MDX content with custom components</div>;
383
}
384
```