0
# Configuration and Types
1

2
Comprehensive configuration system with TypeScript types for stories, arguments, metadata, and global configuration. Provides type safety and extensive customization options.
3

4
## Capabilities
5

6
### Configuration File
7

8
Ladle configuration is defined in `.ladle/config.mjs` using ES module syntax.
9

10
```typescript { .api }
11
/**
12
 * User configuration interface with all optional properties
13
 */
14
interface UserConfig extends RecursivePartial<Config> {
15
  /** Glob pattern for story files */
16
  stories?: string;
17
  /** Default story ID to load on startup */
18
  defaultStory?: string;
19
  /** Function to customize story ordering in sidebar */
20
  storyOrder?: (stories: string[]) => string[];
21
  /** Development server port */
22
  port?: number;
23
  /** Preview server port */
24
  previewPort?: number;
25
  /** Build output directory */
26
  outDir?: string;
27
  /** Whether to expand story tree by default */
28
  expandStoryTree?: boolean;
29
  /** Keyboard shortcuts configuration */
30
  hotkeys?: HotkeyConfig;
31
  /** Built-in addons configuration */
32
  addons?: AddonConfig;
33
}
34

35
interface HotkeyConfig {
36
  search?: string[];
37
  nextStory?: string[];
38
  previousStory?: string[];
39
  nextComponent?: string[];
40
  previousComponent?: string[];
41
  toggleSidebar?: string[];
42
  toggleMode?: string[];
43
  toggleTheme?: string[];
44
  toggleRtl?: string[];
45
  toggleSource?: string[];
46
  toggleControls?: string[];
47
  toggleA11y?: string[];
48
  toggleActions?: string[];
49
  toggleWidth?: string[];
50
  fullscreen?: string[];
51
}
52

53
interface AddonConfig {
54
  control?: { enabled?: boolean };
55
  theme?: { enabled?: boolean };
56
  mode?: { enabled?: boolean };
57
  rtl?: { enabled?: boolean };
58
  source?: { enabled?: boolean };
59
  a11y?: { enabled?: boolean };
60
  msw?: { enabled?: boolean };
61
  action?: { enabled?: boolean };
62
  ladle?: { enabled?: boolean };
63
  width?: { enabled?: boolean };
64
}
65
```
66

67
**Configuration Example:**
68

69
```javascript
70
// .ladle/config.mjs
71
export default {
72
  stories: "src/**/*.stories.{js,jsx,ts,tsx,mdx}",
73
  defaultStory: "components-button--primary",
74
  port: 3000,
75
  previewPort: 8080,
76
  outDir: "component-docs",
77
  expandStoryTree: true,
78
  storyOrder: (stories) => {
79
    // Custom ordering logic
80
    return stories.sort((a, b) => a.localeCompare(b));
81
  },
82
  hotkeys: {
83
    toggleTheme: ["alt+t"],
84
    toggleMode: ["alt+m"]
85
  },
86
  addons: {
87
    a11y: { enabled: true },
88
    msw: { enabled: true },
89
    source: { enabled: false }
90
  }
91
};
92
```
93

94
### Story Configuration Types
95

96
TypeScript interfaces for defining stories, their arguments, and metadata.
97

98
```typescript { .api }
99
/**
100
 * Default export interface for story files containing shared configuration
101
 */
102
interface StoryDefault<P = {}> {
103
  /** Default arguments for all stories in the file */
104
  args?: Args<P>;
105
  /** Argument type definitions for controls */
106
  argTypes?: ArgTypes<P>;
107
  /** Decorators applied to all stories in the file */
108
  decorators?: StoryDecorator<P>[];
109
  /** Story metadata */
110
  meta?: Meta;
111
  /** Story group title */
112
  title?: string;
113
  /** MSW request handlers for API mocking */
114
  msw?: import("msw").RequestHandler[];
115
  /** Additional parameters */
116
  parameters?: { [key: string]: any };
117
}
118

119
/**
120
 * Named export interface for individual stories
121
 */
122
interface Story<P = {}> extends React.FC<P> {
123
  /** Story-specific arguments */
124
  args?: Args<P>;
125
  /** Story-specific argument types */
126
  argTypes?: ArgTypes<P>;
127
  /** Story-specific decorators */
128
  decorators?: StoryDecorator<P>[];
129
  /** Story metadata */
130
  meta?: Meta;
131
  /** Custom story name (overrides function name) */
132
  storyName?: string;
133
  /** MSW handlers for this story */
134
  msw?: import("msw").RequestHandler[];
135
  /** Story-specific parameters */
136
  parameters?: { [key: string]: any };
137
}
138

139
/**
140
 * Story arguments type
141
 */
142
type Args<P = { [key: string]: any }> = Partial<P>;
143

144
/**
145
 * Story decorator function type
146
 */
147
type StoryDecorator<P = {}> = (
148
  Story: React.FC<Partial<P>>,
149
  context: StoryProps
150
) => React.ReactElement;
151
```
152

153
**Story Configuration Examples:**
154

155
```typescript
156
import type { StoryDefault, Story } from "@ladle/react";
157

158
// Default export with shared configuration
159
export default {
160
  title: "Components/Button",
161
  args: {
162
    children: "Button",
163
    variant: "primary"
164
  },
165
  argTypes: {
166
    variant: {
167
      control: { type: "select" },
168
      options: ["primary", "secondary", "danger"]
169
    }
170
  },
171
  decorators: [
172
    (Story) => (
173
      <div style={{ padding: "20px" }}>
174
        <Story />
175
      </div>
176
    )
177
  ]
178
} satisfies StoryDefault;
179

180
// Individual story
181
export const Primary: Story = (args) => <Button {...args} />;
182

183
Primary.args = {
184
  variant: "primary"
185
};
186

187
Primary.argTypes = {
188
  onClick: { action: "clicked" }
189
};
190
```
191

192
### Argument Types Configuration
193

194
Detailed configuration for story controls and argument handling.
195

196
```typescript { .api }
197
/**
198
 * Argument types definition for story controls
199
 */
200
type ArgTypes<P = { [key: string]: any }> = {
201
  [K in keyof P]?: ArgType<P[K]>;
202
};
203

204
/**
205
 * Individual argument type configuration
206
 */
207
interface ArgType<K = any> {
208
  /** Control configuration for the argument */
209
  control?: {
210
    /** Control type name */
211
    type: ControlType;
212
    /** Labels for options in select/radio controls */
213
    labels?: { [key: string]: string };
214
    /** Minimum value for number/range controls */
215
    min?: number;
216
    /** Maximum value for number/range controls */
217
    max?: number;
218
    /** Step value for number/range controls */
219
    step?: number;
220
    /** Additional control-specific options */
221
    [key: string]: any;
222
  };
223
  /** Value mapping for complex controls */
224
  mapping?: { [key: string | number]: any };
225
  /** Available options for select controls */
226
  options?: K[] | unknown;
227
  /** Default value for the argument */
228
  defaultValue?: K;
229
  /** Description text for the argument */
230
  description?: string;
231
  /** Display name for the argument */
232
  name?: string;
233
  /** Action name for event handlers */
234
  action?: string;
235
  /** Additional argument configuration */
236
  [key: string]: any;
237
}
238

239
/**
240
 * Available control types for arguments
241
 */
242
type ControlType = 
243
  | "select"        // Dropdown select
244
  | "multi-select"  // Multiple selection
245
  | "radio"         // Radio buttons (vertical)  
246
  | "inline-radio"  // Radio buttons (horizontal)
247
  | "check"         // Checkboxes (vertical)
248
  | "inline-check"  // Checkboxes (horizontal)
249
  | "background"    // Background color picker
250
  | "color"         // Color picker
251
  | "date"          // Date picker
252
  | "number"        // Number input
253
  | "text"          // Text input
254
  | "boolean"       // Boolean toggle
255
  | "range";        // Range slider
256
```
257

258
**Argument Types Examples:**
259

260
```typescript
261
export default {
262
  argTypes: {
263
    // Select control with options
264
    size: {
265
      control: { type: "select" },
266
      options: ["small", "medium", "large"],
267
      defaultValue: "medium",
268
      description: "Button size variant"
269
    },
270
    
271
    // Number control with range
272
    width: {
273
      control: { 
274
        type: "number",
275
        min: 100, 
276
        max: 500, 
277
        step: 10 
278
      },
279
      defaultValue: 200
280
    },
281
    
282
    // Boolean toggle
283
    disabled: {
284
      control: { type: "boolean" },
285
      defaultValue: false
286
    },
287
    
288
    // Color picker
289
    backgroundColor: {
290
      control: { type: "color" },
291
      defaultValue: "#ffffff"
292
    },
293
    
294
    // Action logging
295
    onClick: {
296
      action: "button-clicked"
297
    },
298
    
299
    // Complex mapping
300
    theme: {
301
      control: { type: "radio" },
302
      options: ["light", "dark"],
303
      mapping: {
304
        light: { background: "#fff", color: "#000" },
305
        dark: { background: "#000", color: "#fff" }
306
      }
307
    }
308
  }
309
} satisfies StoryDefault;
310
```
311

312
### Metadata Types
313

314
Story and global metadata configuration interfaces.
315

316
```typescript { .api }
317
/**
318
 * Story metadata interface
319
 */
320
interface Meta extends KnownMeta {
321
  [key: string]: any;
322
}
323

324
interface KnownMeta {
325
  /** Story title override */
326
  title?: string;
327
  /** Story description */
328
  description?: string;
329
  /** Story tags for organization */
330
  tags?: string[];
331
  /** Story parameters */
332
  parameters?: { [key: string]: any };
333
}
334

335
/**
336
 * JSON metadata structure for build output
337
 */
338
interface MetaJson extends BaseMetaJson<Meta> {
339
  stories: { [key: string]: MetaJsonStory };
340
}
341

342
/**
343
 * Individual story metadata in JSON format
344
 */
345
interface MetaJsonStory extends BaseMetaJsonStory<Meta> {
346
  id: string;
347
  name: string;
348
  title: string;
349
  args: { [key: string]: any };
350
  argTypes: { [key: string]: ArgType };
351
}
352
```
353

354
### Global State Types
355

356
TypeScript definitions for Ladle's internal state management.
357

358
```typescript { .api }
359
/**
360
 * Global state interface for Ladle application
361
 */
362
interface GlobalState {
363
  /** Display mode: full interface or preview only */
364
  mode: ModeState;
365
  /** Theme state: light, dark, or auto */
366
  theme: ThemeState;
367
  /** Action panel state */
368
  action: ActionState;
369
  /** Current story identifier */
370
  story: string;
371
  /** Right-to-left text direction enabled */
372
  rtl: boolean;
373
  /** Source code panel visibility */
374
  source: boolean;
375
  /** Controls panel state */
376
  control: ControlState;
377
  /** Whether controls have been initialized */
378
  controlInitialized: boolean;
379
  /** Current viewport width */
380
  width: number;
381
  /** Whether keyboard shortcuts are enabled */
382
  hotkeys: boolean;
383
}
384

385
/**
386
 * Global action types for state updates
387
 */
388
type GlobalAction = 
389
  | { type: "UpdateAll"; payload: Partial<GlobalState> }
390
  | { type: "UpdateMode"; payload: ModeState }
391
  | { type: "UpdateTheme"; payload: ThemeState }
392
  | { type: "UpdateAction"; payload: ActionState }
393
  | { type: "UpdateStory"; payload: string }
394
  | { type: "UpdateRtl"; payload: boolean }
395
  | { type: "UpdateSource"; payload: boolean }
396
  | { type: "UpdateControl"; payload: ControlState }
397
  | { type: "UpdateControlInitialized"; payload: boolean }
398
  | { type: "UpdateWidth"; payload: number }
399
  | { type: "UpdateHotkeys"; payload: boolean };
400

401
/**
402
 * Enum types for state values
403
 */
404
type ThemeState = "light" | "dark" | "auto";
405
type ModeState = "full" | "preview";
406

407
/**
408
 * Global provider component for Ladle context
409
 */
410
interface GlobalProvider extends React.FC<{
411
  globalState: GlobalState;
412
  dispatch: React.Dispatch<GlobalAction>;
413
  config: Config;
414
  children: React.ReactNode;
415
  storyMeta?: Meta;
416
}> {}
417
```
418

419
### Advanced Configuration
420

421
Extended configuration options for complex setups and integrations.
422

423
```typescript { .api }
424
/**
425
 * Complete configuration interface (internal)
426
 */
427
interface Config extends UserConfig {
428
  // All UserConfig properties are required internally
429
  stories: string;
430
  defaultStory: string;
431
  storyOrder: (stories: string[]) => string[];
432
  port: number;
433
  previewPort: number;
434
  outDir: string;
435
  expandStoryTree: boolean;
436
  hotkeys: Required<HotkeyConfig>;
437
  addons: Required<AddonConfig>;
438
}
439

440
/**
441
 * Utility type for making all properties recursively partial
442
 */
443
type RecursivePartial<T> = {
444
  [P in keyof T]?: T[P] extends object ? RecursivePartial<T[P]> : T[P];
445
};
446
```