Widgetbook is a sandbox for building and cataloging widgets and screens in isolation. It helps you develop and share hard-to-reach states and edge cases without running your whole app. Widgetbook is open-source and free to use.
While developing widgets or screens, you have probably faced one of the following problems:
- Hard-to-reach states: A widget needs to be checked in a specific state (error, loading, empty) that is hard to reach in the running app.
- Time consuming: Testing a single widget means running the whole app, then running it again for every configuration such as dark mode or a different locale.
- API and datasource dependencies: Screens need mocked data to render, which is slow to set up and sometimes not possible at all.
- Collaboration: Sharing UI with designers, QA, and other developers has no obvious home without a catalog.
- Custom design systems are hard to maintain: Components drift from the design over time, edge cases go undocumented, and nobody can tell what already exists, so the same button gets built twice.
Widgetbook covers four jobs: build, test, document, share. Every component gets a page in the catalog, a screenshot per state, and a diff on every pull request.
Catalog every state of a widget without an API or a datasource behind it.
- Stories declare each state of a component.
- Args are generated from your widget's constructor, so every property is a type-safe control in the UI.
- Modes and Addons render the same story under a different theme, locale, viewport, or text scale.
- Mocking injects fake dependencies so screens render standalone.
See Core Concepts for how these fit together.
A scenario pins a story to a fixed state so it renders the same way every time.
- Write that state once and reuse it while developing, while reviewing, and in automated tests.
flutter testrenders every scenario and saves a screenshot.- Accessibility guidelines check each screenshot for tap-target size, missing labels, and text contrast.
- Visual tests in Widgetbook Cloud compare the screenshots against the previous build and show what changed in the pull request.
DocBlocks generate component documentation from the code you already wrote. Blocks are customizable globally or per component.
Publish the catalog so the whole team has access without running Flutter code.
- Embed a single story in your own docs site.
- Publish to Widgetbook Cloud for a hosted build per commit and reviews with sign-off from designers and QA.
In a generative UI app, the model composes screens at runtime from a fixed set of approved widgets. Those screens are only as good as the widgets you hand the model.
- A catalog entry and a story describe the same widget, so one definition covers both.
- Generated screens cannot be captured up front, but every widget the model picks from can.
- Real model output replays as a scenario and becomes a regression test.
See GenUI.
New in v4: generated, type-safe declarations replace v3's annotations and knobs. See What's new in v4.
Building UI in isolation
Lotum speeds up app development by building widgets in isolation.
1KOMMA5° on an in-house design system used across 3 apps.
LeanCode on a design system template shared with every new client.