DocBlocks

DocBlocks are composable widgets that render different parts of your component documentation. Each block serves a specific purpose including displaying component names, doc comments, live story examples, argument tables, and more.

Core DocBlocks

ComponentNameDocBlock

Displays the name of the current component as a title in the documentation panel.

Usage:

const ComponentNameDocBlock()

DartCommentDocBlock

Displays the Dart documentation comments for the current component. Documentation comments are automatically extracted from your source code by the build_runner.

Usage:

const DartCommentDocBlock()

StoriesDocBlock

Displays all stories defined for the current component including their names, live previews, and a table displaying the default Arg values.

By default, each story preview is rendered inside a fixed-height container (500px) to provide bounded constraints. This prevents layout errors for widgets that require finite height such as Scaffold, Overlay, or Expanded.

Usage:

// Default: fixed height of 500px per story
const StoriesDocBlock()

// Custom fixed height
const StoriesDocBlock(height: 800)

// Unconstrained: stories render at their natural size
// Use this for simple widgets like buttons, cards, or badges
const StoriesDocBlock.unconstrained()

StoryDocBlock

Displays a single story with its live preview and argument table. Used internally by StoriesDocBlock but can also be used directly for per-story control.

Usage:

StoryDocBlock(story: myStory)                          // Fixed height (500px)
StoryDocBlock(story: myStory, height: 800)             // Custom fixed height
StoryDocBlock.unconstrained(story: myStory)            // Unconstrained

PrimaryStoryDocBlock

Displays only the first story for the component. Useful for highlighting the main example.

Usage:

const PrimaryStoryDocBlock()                // Fixed height (500px)
const PrimaryStoryDocBlock.unconstrained()  // Unconstrained

Text & Layout DocBlocks

TitleDocBlock

Displays text as a large title using headlineLarge text style.

Usage:

TitleDocBlock(title: 'My Component')

SubtitleDocBlock

Displays text as a medium-sized subtitle using headlineMedium text style.

Usage:

SubtitleDocBlock(title: 'Examples')

TextDocBlock

Displays a block of text using the default body text style.

Usage:

const TextDocBlock('This is a description of my component.')

Composition

ComposerDocBlock

Stacks multiple DocBlock widgets vertically with consistent spacing.

Usage:

ComposerDocBlock(
  children: [
    const TitleDocBlock(title: 'Button'),
    const TextDocBlock('A customizable button component.'),
    const PrimaryStoryDocBlock(),
  ],
)

WidgetDocBlock

Embeds any custom Flutter widget into your documentation.

Usage:

WidgetDocBlock(
  Container(
    padding: const EdgeInsets.all(16),
    color: Colors.blue.shade50,
    child: const Text('Custom widget in docs'),
  ),
)

Creating Custom DocBlocks

You can create your own DocBlock by following the steps outlined in the Custom Blocks guide.