0
# Documentation Blocks
1

2
Core React components for building comprehensive documentation pages that automatically extract and display story metadata, source code, and interactive elements.
3

4
## Capabilities
5

6
### Canvas Block
7

8
Renders stories with source code display and interactive toolbar, providing the primary story viewing experience.
9

10
```typescript { .api }
11
/**
12
 * Renders stories with source code and toolbar
13
 * @param props - Canvas configuration options
14
 * @returns React component displaying story with controls
15
 */
16
function Canvas(props: CanvasProps): React.ReactElement;
17

18
interface CanvasProps {
19
  /** Story to render */
20
  of?: ModuleExport;
21
  /** CSF file exports for unattached MDX */
22
  meta?: ModuleExports;
23
  /** Show/hide toolbar */
24
  withToolbar?: boolean;
25
  /** Source panel visibility state */
26
  sourceState?: 'hidden' | 'shown' | 'none';
27
  /** Story layout mode */
28
  layout?: 'padded' | 'fullscreen' | 'centered';
29
  /** CSS class name */
30
  className?: string;
31
  /** Custom toolbar actions */
32
  additionalActions?: Array<{
33
    title: string;
34
    onClick: () => void;
35
    disabled?: boolean;
36
  }>;
37
  /** Source code configuration */
38
  source?: SourceProps;
39
  /** Story display configuration */
40
  story?: StoryProps;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { Canvas } from "@storybook/addon-docs/blocks";
48
import * as ButtonStories from "./Button.stories";
49

50
// Basic canvas
51
<Canvas of={ButtonStories.Primary} />
52

53
// Canvas with custom configuration
54
<Canvas 
55
  of={ButtonStories.Primary}
56
  withToolbar={true}
57
  sourceState="shown"
58
  layout="centered"
59
/>
60
```
61

62
### Story Block
63

64
Renders individual stories inline or in iframe with configurable display options.
65

66
```typescript { .api }
67
/**
68
 * Renders individual stories
69
 * @param props - Story configuration options
70
 * @returns React component displaying single story
71
 */
72
function Story(props: StoryProps): React.ReactElement;
73

74
interface StoryProps {
75
  /** Story export to render */
76
  of?: ModuleExport;
77
  /** CSF file exports for context */
78
  meta?: ModuleExports;
79
  /** Render inline or in iframe */
80
  inline?: boolean;
81
  /** Story height for iframe mode */
82
  height?: string;
83
  /** Auto-run play function */
84
  autoplay?: boolean;
85
  /** Internal: force initial args */
86
  __forceInitialArgs?: boolean;
87
  /** Internal: mark as primary story */
88
  __primary?: boolean;
89
}
90
```
91

92
### ArgsTable Block
93

94
Displays component argument types and controls in a comprehensive table format.
95

96
```typescript { .api }
97
/**
98
 * Displays component argument types in table format
99
 * @param props - ArgsTable configuration
100
 * @returns React component with args documentation
101
 */
102
function ArgTypes(props: ArgTypesProps): React.ReactElement;
103

104
interface ArgTypesProps {
105
  /** Component or CSF file to extract args from */
106
  of?: React.ComponentType | ModuleExports;
107
  /** Properties to include */
108
  include?: PropDescriptor;
109
  /** Properties to exclude */
110
  exclude?: PropDescriptor;
111
  /** Sorting configuration */
112
  sort?: SortType;
113
}
114

115
/**
116
 * Pure args table component without automatic extraction
117
 */
118
const PureArgsTable: React.FC<ArgsTableProps>;
119

120
interface ArgsTableProps {
121
  rows: ArgType[];
122
  args?: Args;
123
  globals?: Args;
124
  updateArgs?: (args: Args) => void;
125
  resetArgs?: () => void;
126
  inAddonPanel?: boolean;
127
  sort?: SortType;
128
}
129
```
130

131
### Description Block
132

133
Displays component or story descriptions from various sources with automatic fallback.
134

135
```typescript { .api }
136
/**
137
 * Displays component/story descriptions from various sources
138
 * @param props - Description configuration
139
 * @returns React component with description content
140
 */
141
function Description(props: DescriptionProps): React.ReactElement;
142

143
interface DescriptionProps {
144
  /** Where to get description from */
145
  of?: Of;
146
  /** Description type */
147
  type?: DescriptionType;
148
  /** Markdown content */
149
  children?: string;
150
}
151

152
enum DescriptionType {
153
  INFO = 'info',
154
  NOTES = 'notes', 
155
  DOCGEN = 'docgen',
156
  AUTO = 'auto'
157
}
158
```
159

160
### Source Block
161

162
Displays syntax-highlighted source code with formatting and transformation options.
163

164
```typescript { .api }
165
/**
166
 * Displays syntax-highlighted source code
167
 * @param props - Source configuration options
168
 * @returns React component with formatted code
169
 */
170
function Source(props: SourceProps): React.ReactElement;
171

172
interface SourceProps {
173
  /** Story to show source for */
174
  of?: ModuleExport;
175
  /** Direct code to display */
176
  code?: string;
177
  /** Programming language for syntax highlighting */
178
  language?: SupportedLanguage;
179
  /** Code formatting options */
180
  format?: boolean | 'dedent' | string;
181
  /** Dark theme */
182
  dark?: boolean;
183
  /** Source extraction type */
184
  type?: 'auto' | 'code' | 'dynamic';
185
  /** Code transformation function */
186
  transform?: (code: string, storyContext: any) => string;
187
}
188

189
type SupportedLanguage = 
190
  | 'javascript' | 'typescript' | 'jsx' | 'tsx'
191
  | 'html' | 'css' | 'scss' | 'json' 
192
  | 'markdown' | 'yaml' | 'bash';
193
```
194

195
### Stories Block
196

197
Displays all component stories in an organized layout with optional primary story.
198

199
```typescript { .api }
200
/**
201
 * Displays all component stories in organized layout
202
 * @param props - Stories configuration
203
 * @returns React component with all stories
204
 */
205
function Stories(props: StoriesProps): React.ReactElement;
206

207
interface StoriesProps {
208
  /** Section title */
209
  title?: React.ReactElement | string;
210
  /** Include primary story */
211
  includePrimary?: boolean;
212
}
213
```
214

215
### Primary Block
216

217
Displays the primary story of a component with enhanced presentation.
218

219
```typescript { .api }
220
/**
221
 * Displays the primary story with enhanced presentation
222
 * @param props - Primary story configuration
223
 * @returns React component with primary story
224
 */
225
function Primary(props: PrimaryProps): React.ReactElement;
226

227
interface PrimaryProps {
228
  /** Where to get primary story from */
229
  of?: Of;
230
}
231
```
232

233
### Text and Layout Blocks
234

235
Structural components for organizing documentation content.
236

237
```typescript { .api }
238
/**
239
 * Main page title component
240
 */
241
function Title(props: {children?: React.ReactNode}): React.ReactElement;
242

243
/**
244
 * Page subtitle component
245
 */
246
function Subtitle(props: {children?: React.ReactNode}): React.ReactElement;
247

248
/**
249
 * Section heading component
250
 */
251
function Heading(props: {children?: React.ReactNode}): React.ReactElement;
252

253
/**
254
 * Subsection heading component
255
 */
256
function Subheading(props: {children?: React.ReactNode}): React.ReactElement;
257

258
/**
259
 * Associates MDX file with CSF file metadata
260
 */
261
function Meta(props: {of?: ModuleExports; title?: string}): React.ReactElement;
262

263
/**
264
 * Renders markdown content in docs
265
 */
266
function Markdown(props: {children: string}): React.ReactElement;
267

268
/**
269
 * Creates linkable anchors in documentation
270
 */
271
function Anchor(props: {storyId: string}): React.ReactElement;
272

273
/**
274
 * Layout wrapper component
275
 */
276
function Wrapper(props: {children: React.ReactNode}): React.ReactElement;
277

278
/**
279
 * Removes Storybook styling from content
280
 */
281
function Unstyled(props: {children: React.ReactNode}): React.ReactElement;
282
```
283

284
### Context and Hooks
285

286
React context and hooks for accessing Storybook data within documentation blocks.
287

288
```typescript { .api }
289
/**
290
 * Main context for docs functionality 
291
 */
292
const DocsContext: React.Context<DocsContextProps>;
293

294
/**
295
 * Resolves 'of' prop to component/story/meta references
296
 * @param moduleExportOrType - Reference to resolve
297
 * @param validTypes - Valid resolution types
298
 * @returns Resolved reference data
299
 */
300
function useOf<TType>(
301
  moduleExportOrType: Of, 
302
  validTypes?: TType[]
303
): ResolvedOf<TType>;
304

305
/**
306
 * Manages story arguments with update/reset functionality
307
 * @returns Tuple of current args, update function, reset function
308
 */
309
function useArgs(): [Args, (args: Args) => void, () => void];
310

311
/**
312
 * Manages global parameters
313
 * @returns Tuple of current globals, update function
314
 */
315
function useGlobals(): [Args, (globals: Args) => void];
316

317
/**
318
 * Retrieves story data and context
319
 * @param storyId - Story identifier
320
 * @returns Story data and context
321
 */
322
function useStory(storyId?: string): StoryContext | null;
323

324
/**
325
 * Transforms source code for display with formatting
326
 * @param story - Story context
327
 * @param source - Source configuration
328
 * @returns Transformed source code
329
 */
330
function useTransformCode(story: any, source?: SourceProps): string;
331

332
type Of = 
333
  | React.ComponentType
334
  | ModuleExports
335
  | ModuleExport;
336

337
interface ResolvedOf<TType> {
338
  type: TType;
339
  story?: any;
340
  component?: React.ComponentType;
341
  meta?: any;
342
}
343
```
344

345
## UI Components  
346

347
### Styleguide Components
348

349
Specialized components for documenting design systems and component libraries.
350

351
```typescript { .api }
352
/**
353
 * Color documentation container
354
 */
355
function ColorPalette(props: ColorPaletteProps): React.ReactElement;
356

357
/**
358
 * Individual color display with title and subtitle
359
 */
360
function ColorItem(props: ColorItemProps): React.ReactElement;
361

362
interface ColorPaletteProps {
363
  children: React.ReactNode;
364
}
365

366
interface ColorItemProps {
367
  /** Color name/title */
368
  title: string;
369
  /** Color description */
370
  subtitle: string;
371
  /** Color values as array or object */
372
  colors: Colors;
373
}
374

375
type Colors = string[] | Record<string, string>;
376

377
/**
378
 * Icon documentation container
379
 */
380
function IconGallery(props: IconGalleryProps): React.ReactElement;
381

382
/**
383
 * Individual icon display with name
384
 */
385
function IconItem(props: IconItemProps): React.ReactElement;
386

387
interface IconGalleryProps {
388
  children: React.ReactNode;
389
}
390

391
interface IconItemProps {
392
  /** Icon name */
393
  name: string;
394
  /** Icon element */
395
  children?: React.ReactNode;
396
}
397

398
/**
399
 * Typography demonstration component
400
 */
401
function Typeset(props: TypesetProps): React.ReactElement;
402

403
interface TypesetProps {
404
  /** Font family name */
405
  fontFamily?: string;
406
  /** Array of font sizes to display */
407
  fontSizes: (string | number)[];
408
  /** Font weight */
409
  fontWeight?: number;
410
  /** Sample text to display */
411
  sampleText?: string;
412
}
413
```
414

415
### Table of Contents
416

417
Automatically generated table of contents from documentation headings.
418

419
```typescript { .api }
420
/**
421
 * Generated table of contents from headings
422
 * @param props - TOC configuration
423
 * @returns React component with navigation links
424
 */
425
function TableOfContents(props: TableOfContentsProps): React.ReactElement;
426

427
interface TableOfContentsProps {
428
  /** CSS class name */
429
  className?: string;
430
  /** Heading levels to include */
431
  headingSelector?: string;
432
  /** Disable TOC generation */
433
  disable?: boolean;
434
}
435
```
436

437
### DocsPage Components
438

439
Components for automatic documentation page generation and container management.
440

441
```typescript { .api }
442
/**
443
 * Automatic documentation page component
444
 * Generates comprehensive docs from story metadata
445
 */
446
function DocsPage(): React.ReactElement;
447

448
/**
449
 * Container for docs pages with theme and context setup
450
 * @param props - Container configuration
451
 * @returns React component wrapping docs content
452
 */
453
function DocsContainer(props: DocsContainerProps): React.ReactElement;
454

455
/**
456
 * Story wrapper component for docs rendering
457
 * @param props - Story wrapper configuration  
458
 * @returns React component wrapping individual stories
459
 */
460
function DocsStory(props: DocsStoryProps): React.ReactElement;
461

462
/**
463
 * Main docs rendering component
464
 * @param props - Docs configuration
465
 * @returns React component with complete docs
466
 */
467
function Docs(props: DocsProps): React.ReactElement;
468

469
interface DocsContainerProps {
470
  /** Docs rendering context */
471
  context: DocsContextProps;
472
  /** Child components */
473
  children: React.ReactNode;
474
  /** Theme configuration */
475
  theme?: ThemeVars;
476
}
477

478
interface DocsStoryProps {
479
  /** Story export */
480
  of: ModuleExport;
481
  /** Expanded view mode */
482
  expanded?: boolean;
483
  /** Include source */
484
  withSource?: boolean;
485
}
486

487
interface DocsProps {
488
  /** Documentation renderer */
489
  renderer?: DocsRenderer;
490
  /** Layout configuration */
491
  layout?: 'sidebar' | 'canvas';
492
}
493
```
494

495
### External Docs Components
496

497
Components for external documentation integration and custom docs pages.
498

499
```typescript { .api }
500
/**
501
 * External docs integration component
502
 * @param props - External docs configuration
503
 * @returns React component with external docs
504
 */
505
function ExternalDocs(props: ExternalDocsProps): React.ReactElement;
506

507
/**
508
 * Container for external documentation
509
 * @param props - External container configuration
510
 * @returns React component wrapping external content
511
 */
512
function ExternalDocsContainer(props: ExternalDocsContainerProps): React.ReactElement;
513

514
interface ExternalDocsProps {
515
  /** External docs URL or content */
516
  source: string | React.ComponentType;
517
  /** Display title */
518
  title?: string;
519
  /** Integration mode */
520
  mode?: 'iframe' | 'embed';
521
}
522

523
interface ExternalDocsContainerProps {
524
  /** Container content */
525
  children: React.ReactNode;
526
  /** Custom styling */
527
  className?: string;
528
}
529
```
530

531
### Block Parameter Types
532

533
Configuration interfaces for customizing block behavior and appearance.
534

535
```typescript { .api }
536
interface CanvasBlockParameters {
537
  /** Source code display configuration */
538
  sourceState?: 'hidden' | 'shown' | 'none';
539
  /** Story layout in canvas */
540
  layout?: 'padded' | 'fullscreen' | 'centered';
541
  /** Disable source snippets */
542
  disable?: boolean;
543
  /** Additional actions for toolbar */
544
  additionalActions?: ActionItem[];
545
  /** Custom source transformation */
546
  withSource?: SourceType;
547
}
548

549
interface SourceBlockParameters {
550
  /** Source code type */
551
  type?: 'auto' | 'code' | 'dynamic';
552
  /** Code language */
553
  language?: SupportedLanguage;
554
  /** Code formatting */
555
  format?: boolean | 'dedent';
556
  /** Exclude from source */
557
  excludeDecorators?: boolean;
558
  /** Source transformation function */
559
  transform?: (code: string, context: any) => string;
560
}
561

562
interface StoryBlockParameters {
563
  /** Auto-play interaction tests */
564
  autoplay?: boolean;
565
  /** Inline rendering mode */
566
  inline?: boolean;
567
  /** Story height for iframe */
568
  height?: string;
569
  /** Primary story marker */
570
  iframeHeight?: number;
571
}
572

573
interface ActionItem {
574
  /** Action title */
575
  title: string;
576
  /** Click handler */
577
  onClick: () => void;
578
  /** Disabled state */
579
  disabled?: boolean;
580
  /** Icon component */
581
  icon?: React.ComponentType;
582
}
583

584
type SourceType = 
585
  | 'auto'
586
  | 'code' 
587
  | 'dynamic'
588
  | 'none';
589

590
interface ArgType {
591
  /** Argument name */
592
  name: string;
593
  /** Argument description */
594
  description?: string;
595
  /** Default value */
596
  defaultValue?: any;
597
  /** Type information */
598
  type?: {
599
    name: string;
600
    required?: boolean;
601
  };
602
  /** Control configuration */
603
  control?: ControlConfig;
604
  /** Table configuration */
605
  table?: {
606
    category?: string;
607
    subcategory?: string;
608
    disable?: boolean;
609
  };
610
}
611

612
interface Args {
613
  [key: string]: any;
614
}
615

616
interface ControlConfig {
617
  /** Control type */
618
  type?: string;
619
  /** Control options */
620
  options?: any[];
621
  /** Control labels */
622
  labels?: Record<string, string>;
623
}
624

625
interface ThemeVars {
626
  /** Base theme colors */
627
  base?: 'light' | 'dark';
628
  /** Color overrides */
629
  colorPrimary?: string;
630
  colorSecondary?: string;
631
  /** Typography overrides */
632
  fontBase?: string;
633
  fontCode?: string;
634
  /** Brand configuration */
635
  brandTitle?: string;
636
  brandUrl?: string;
637
  brandImage?: string;
638
}
639

640
interface DocsRenderer {
641
  /** Render method */
642
  render: (story: any, context: any) => React.ReactElement;
643
  /** Story configuration */
644
  storyContext?: any;
645
  /** Global configuration */
646
  globals?: Args;
647
}
648
```