Customize Documentation
Widgetbook's documentation system is fully customizable through the docsBuilder function.
You can customize documentation at two levels: globally for all components, or individually for specific components.
Basic Example
import 'package:widgetbook/widgetbook.dart';
final config = Config(
components: components,
docsBuilder: () => [
const ComponentNameDocBlock(),
const PrimaryStoryDocBlock(),
],
addons: [
// Your addons here
],
);
Story Preview Height
By default, story previews in docs are rendered inside a fixed-height container (500px). This ensures widgets that require bounded constraints (e.g. Scaffold, Overlay, Expanded) render correctly.
For simple widgets with a natural intrinsic height (e.g. buttons, cards), you can opt into unconstrained rendering using the .unconstrained() constructor:
Global Unconstrained Rendering
final config = Config(
components: components,
docsBuilder: () => [
const ComponentNameDocBlock(),
const DartCommentDocBlock(),
const StoriesDocBlock.unconstrained(),
],
);
Per-Component Override
// Screen-level component: use a taller fixed height
final meta = Meta<MyScreen>(
docsBuilder: (blocks) => blocks.replaceFirst<StoriesDocBlock>(
const StoriesDocBlock(height: 800),
),
);
// Simple widget: use unconstrained rendering
final meta = Meta<MyButton>(
docsBuilder: (blocks) => blocks.replaceFirst<StoriesDocBlock>(
const StoriesDocBlock.unconstrained(),
),
);
Component-Level Customization
Override documentation for specific components via the docsBuilder parameter in the Meta tag.
Basic Override
import 'package:widgetbook/widgetbook.dart';
final meta = Meta<MyButton>(
docsBuilder: (blocks) => [
const ComponentNameDocBlock(),
const TextDocBlock('A custom button component for our app.'),
const StoriesDocBlock(),
],
);
Modifying Default Blocks
The docsBuilder function receives the default blocks list, allowing you to modify it:
final meta = Meta<MyButton>(
docsBuilder: (blocks) => blocks.replaceFirst<DartCommentDocBlock>(
const TextDocBlock('Custom description for this specific component.'),
),
);
Adding Blocks
Add blocks before or after existing ones using extension methods:
final meta = Meta<MyButton>(
docsBuilder: (blocks) => blocks
..insertAfter<ComponentNameDocBlock>(
const TextDocBlock('⭐ This is our most popular component!'),
),
);
Complex Customization
Combine multiple modifications:
final meta = Meta<MyComplexWidget>(
docsBuilder: (blocks) => blocks
..insertBefore<DartCommentDocBlock>(
WidgetDocBlock(
Image.asset('assets/diagram.png'),
),
)
..replaceFirst<StoriesDocBlock>(
const PrimaryStoryDocBlock(), // Only show primary example
)
..insertAfter<PrimaryStoryDocBlock>(
const TextDocBlock('For more examples, see our style guide.'),
),
);