0
# Interactive Controls
1

2
Control components that provide interactive interfaces for manipulating story arguments in real-time, supporting all common input types with full type safety and validation.
3

4
## Capabilities
5

6
### Controls Block
7

8
Main component that renders interactive controls for all story arguments with automatic type detection and configuration.
9

10
```typescript { .api }
11
/**
12
 * Interactive controls for manipulating story arguments
13
 * @param props - Controls configuration options
14
 * @returns React component with argument controls
15
 */
16
function Controls(props: ControlsProps): React.ReactElement;
17

18
interface ControlsProps {
19
  /** Component or CSF file to extract controls from */
20
  of?: React.ComponentType | ModuleExports;
21
  /** Controls to include */
22
  include?: PropDescriptor;
23
  /** Controls to exclude */
24
  exclude?: PropDescriptor;
25
  /** Sorting configuration */
26
  sort?: SortType;
27
}
28
```
29

30
### Control Base Interface
31

32
Base interface shared by all control components with common properties and event handlers.
33

34
```typescript { .api }
35
interface ControlProps<T> {
36
  /** Control name/identifier */
37
  name: string;
38
  /** Current value */
39
  value?: T;
40
  /** Default value */
41
  defaultValue?: T;
42
  /** Argument type metadata */
43
  argType?: ArgType;
44
  /** Value change handler */
45
  onChange: (value?: T) => T | void;
46
  /** Focus event handler */
47
  onFocus?: (evt: any) => void;
48
  /** Blur event handler */
49
  onBlur?: (evt: any) => void;
50
}
51

52
interface ArgType {
53
  name: string;
54
  description?: string;
55
  defaultValue?: any;
56
  type?: {
57
    name: string;
58
    value?: any;
59
  };
60
  table?: {
61
    type?: { summary: string };
62
    defaultValue?: { summary: string };
63
    category?: string;
64
  };
65
  control?: ControlType | false;
66
  if?: {
67
    arg: string;
68
    exists?: boolean;
69
    eq?: any;
70
    neq?: any;
71
    truthy?: boolean;
72
  };
73
}
74
```
75

76
### Boolean Control
77

78
Toggle control for boolean values with customizable styling and behavior.
79

80
```typescript { .api }
81
/**
82
 * Toggle control for boolean values
83
 * @param props - Boolean control configuration
84
 * @returns React component with checkbox/toggle input
85
 */
86
function BooleanControl(props: BooleanProps): React.ReactElement;
87

88
interface BooleanProps extends ControlProps<BooleanValue> {
89
  /** Boolean control configuration */
90
  config?: BooleanConfig;
91
}
92

93
type BooleanValue = boolean;
94

95
interface BooleanConfig {
96
  /** Disable the control */
97
  disable?: boolean;
98
}
99
```
100

101
### Color Control
102

103
Color picker control with preset colors and advanced color selection capabilities.
104

105
```typescript { .api }
106
/**
107
 * Color picker with presets and advanced selection
108
 * @param props - Color control configuration  
109
 * @returns React component with color picker interface
110
 */
111
const ColorControl: React.FC<ColorProps>;
112

113
interface ColorProps extends ControlProps<ColorValue> {
114
  /** Color control configuration */
115
  config?: ColorConfig;
116
}
117

118
type ColorValue = string;
119

120
interface ColorConfig {
121
  /** Array of preset color values */
122
  presetColors?: string[];
123
  /** Start with color picker open */
124
  startOpen?: boolean;
125
}
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
// Basic color control
132
<ColorControl 
133
  name="backgroundColor"
134
  value="#ffffff"
135
  onChange={(color) => setBackgroundColor(color)}
136
/>
137

138
// With preset colors
139
<ColorControl 
140
  name="themeColor"
141
  value="#007acc"
142
  config={{
143
    presetColors: ['#007acc', '#ff6b6b', '#4ecdc4', '#45b7d1'],
144
    startOpen: false
145
  }}
146
  onChange={(color) => setThemeColor(color)}
147
/>
148
```
149

150
### Date Control
151

152
Date and time input control with flexible value formats and validation.
153

154
```typescript { .api }
155
/**
156
 * Date/time input control with validation
157
 * @param props - Date control configuration
158
 * @returns React component with date/time input
159
 */
160
function DateControl(props: DateProps): React.ReactElement;
161

162
interface DateProps extends ControlProps<DateValue> {
163
  /** Date control configuration */
164
  config?: DateConfig;
165
}
166

167
type DateValue = Date | number;
168

169
interface DateConfig {
170
  /** Disable the control */
171
  disable?: boolean;
172
}
173
```
174

175
### Number Control
176

177
Numeric input control with range validation and step configuration.
178

179
```typescript { .api }
180
/**
181
 * Numeric input with validation and constraints
182
 * @param props - Number control configuration
183
 * @returns React component with number input
184
 */
185
function NumberControl(props: NumberProps): React.ReactElement;
186

187
interface NumberProps extends ControlProps<NumberValue> {
188
  /** Number control configuration */
189
  config?: NumberConfig;
190
}
191

192
type NumberValue = number;
193

194
interface NumberConfig {
195
  /** Minimum allowed value */
196
  min?: number;
197
  /** Maximum allowed value */
198
  max?: number;
199
  /** Step increment */
200
  step?: number;
201
}
202
```
203

204
### Range Control
205

206
Slider control for numeric ranges with visual feedback and constraints.
207

208
```typescript { .api }
209
/**
210
 * Slider for numeric ranges with visual feedback
211
 * @param props - Range control configuration
212
 * @returns React component with range slider
213
 */
214
function RangeControl(props: RangeProps): React.ReactElement;
215

216
interface RangeProps extends ControlProps<RangeValue> {
217
  /** Range control configuration */
218
  config?: RangeConfig;
219
}
220

221
type RangeValue = number;
222

223
interface RangeConfig extends NumberConfig {
224
  /** Additional range-specific options */
225
}
226
```
227

228
### Text Control
229

230
Text input control with length validation and formatting options.
231

232
```typescript { .api }
233
/**
234
 * Text input field with validation
235
 * @param props - Text control configuration
236
 * @returns React component with text input
237
 */
238
function TextControl(props: TextProps): React.ReactElement;
239

240
interface TextProps extends ControlProps<TextValue> {
241
  /** Text control configuration */
242
  config?: TextConfig;
243
}
244

245
type TextValue = string;
246

247
interface TextConfig {
248
  /** Maximum text length */
249
  maxLength?: number;
250
}
251
```
252

253
### Object Control
254

255
JSON object editor with tree view and validation for complex data structures.
256

257
```typescript { .api }
258
/**
259
 * JSON object editor with tree view and validation
260
 * @param props - Object control configuration  
261
 * @returns React component with object editor
262
 */
263
function ObjectControl(props: ObjectProps): React.ReactElement;
264

265
interface ObjectProps extends ControlProps<ObjectValue> {
266
  /** Object control configuration */
267
  config?: ObjectConfig;
268
}
269

270
type ObjectValue = any;
271

272
interface ObjectConfig {
273
  /** Disable the control */
274
  disable?: boolean;
275
}
276
```
277

278
### Files Control
279

280
File upload control supporting single and multiple file selection.
281

282
```typescript { .api }
283
/**
284
 * File upload control for file inputs
285
 * @param props - Files control configuration
286
 * @returns React component with file input
287
 */
288
function FilesControl(props: FilesProps): React.ReactElement;
289

290
interface FilesProps extends ControlProps<FilesValue> {
291
  /** Files control configuration */
292
  config?: FilesConfig;
293
}
294

295
type FilesValue = FileList | File[] | null;
296

297
interface FilesConfig {
298
  /** Accept file types */
299
  accept?: string;
300
  /** Allow multiple files */
301
  multiple?: boolean;
302
}
303
```
304

305
## Option Controls
306

307
Specialized controls for handling predefined sets of options with various selection interfaces.
308

309
### Select Control
310

311
Dropdown selection control for choosing from predefined options.
312

313
```typescript { .api }
314
/**
315
 * Dropdown selection control
316
 * @param props - Select control configuration
317
 * @returns React component with select dropdown
318
 */
319
function SelectControl(props: SelectProps): React.ReactElement;
320

321
interface SelectProps extends ControlProps<any> {
322
  /** Select control configuration */
323
  config?: OptionsConfig;
324
}
325
```
326

327
### Radio Control
328

329
Radio button group for single selection from predefined options.
330

331
```typescript { .api }
332
/**
333
 * Radio button group for single selection
334
 * @param props - Radio control configuration
335
 * @returns React component with radio buttons
336
 */
337
function RadioControl(props: RadioProps): React.ReactElement;
338

339
interface RadioProps extends ControlProps<any> {
340
  /** Radio control configuration */
341
  config?: OptionsConfig;
342
}
343
```
344

345
### Checkbox Control
346

347
Checkbox group for multiple selection from predefined options.
348

349
```typescript { .api }
350
/**
351
 * Checkbox group for multiple selection
352
 * @param props - Checkbox control configuration
353
 * @returns React component with checkbox group
354
 */
355
function CheckboxControl(props: CheckboxProps): React.ReactElement;
356

357
interface CheckboxProps extends ControlProps<any[]> {
358
  /** Checkbox control configuration */
359
  config?: OptionsConfig;
360
}
361
```
362

363
### Options Control
364

365
Generic base control for all option-based controls with flexible configuration.
366

367
```typescript { .api }
368
/**
369
 * Generic options control base
370
 * @param props - Options control configuration
371
 * @returns React component with options interface
372
 */
373
function OptionsControl(props: OptionsProps): React.ReactElement;
374

375
interface OptionsProps extends ControlProps<any> {
376
  /** Options control configuration */
377
  config?: OptionsConfig;
378
}
379

380
interface OptionsConfig {
381
  /** Available option values */
382
  options?: OptionsConfigOptions;
383
  /** Labels for options */  
384
  labels?: Record<string, string>;
385
  /** Control type override */
386
  type?: OptionsControlType;
387
}
388

389
type OptionsConfigOptions = 
390
  | string[] 
391
  | number[]
392
  | { label: string; value: any }[]
393
  | Record<string, any>;
394

395
type OptionsControlType = 
396
  | 'select'
397
  | 'multi-select' 
398
  | 'radio'
399
  | 'inline-radio'
400
  | 'check'
401
  | 'inline-check';
402
```
403

404
## Control Type System
405

406
Type definitions for the control system with comprehensive configuration options.
407

408
```typescript { .api }
409
type ControlType = 
410
  | 'boolean'
411
  | 'color'
412
  | 'date'
413
  | 'number'
414
  | 'range'
415
  | 'text'
416
  | 'object'
417
  | 'file'
418
  | 'select'
419
  | 'multi-select'
420
  | 'radio'
421
  | 'inline-radio'
422
  | 'check'
423
  | 'inline-check';
424

425
type Control = 
426
  | BooleanConfig
427
  | ColorConfig
428
  | DateConfig
429
  | NumberConfig
430
  | RangeConfig
431
  | TextConfig
432
  | ObjectConfig
433
  | FilesConfig
434
  | OptionsConfig;
435

436
type PropDescriptor = string | string[] | RegExp;
437

438
type SortType = 'alpha' | 'requiredFirst' | 'none';
439

440
interface Renderer {
441
  component?: React.ComponentType;
442
  [key: string]: any;
443
}
444
```
445

446
**Usage Examples:**
447

448
```typescript
449
import { Controls, BooleanControl, ColorControl } from "@storybook/addon-docs/blocks";
450

451
// Automatic controls for all args
452
<Controls of={ButtonStories} />
453

454
// Filtered controls
455
<Controls 
456
  of={ButtonStories}
457
  include={['size', 'variant', 'disabled']}
458
  sort="alpha"
459
/>
460

461
// Individual controls
462
<BooleanControl 
463
  name="disabled"
464
  value={false}
465
  onChange={(value) => updateArgs({ disabled: value })}
466
/>
467

468
<ColorControl
469
  name="color"
470
  value="#007acc"
471
  config={{ presetColors: ['#007acc', '#ff6b6b'] }}
472
  onChange={(value) => updateArgs({ color: value })}
473
/>
474
```