Widgetbook: a Storybook-style sandbox for Flutter widgets

Storybook's idea, brought to Flutter

The README describes the open-source Widgetbook as a sandbox for building widgets and screens in isolation, and says plainly that it is inspired by Storybook.js. The tagline under the logo is build Flutter widgets and screens in isolation.

That is a recognisable idea transplanted to a different ecosystem. In a JavaScript project, Storybook lets you mount a component in a browser with arbitrary props and no application around it. The problem it solves is that a component in a real application is reachable only through the state of the application, so the states that matter, the empty list, the loading spinner, the error, the text that overflows, the locale with longer words, are exactly the ones that are hardest to reach deliberately. A component catalogue is also a way of answering what exists, which is a question that gets harder as a design system grows.

Widgetbook's version of that idea has three declared features. You can build UI components and pages in isolation without fussing with data, APIs or business logic. You can mock hard to reach edge cases, render widgets in key states that are tricky to reproduce in an app, and then save those states as use cases to revisit during development, testing and QA. And you can catalogue all of your widgets, creating your own widget library that gives an overview of what you have already built.

The third feature is worth pausing on, because it is the one that changes how a team works rather than how a developer works. A catalogue of components with their states is documentation that cannot drift from the code, because the states are executed, and a designer or a product manager can look at it without running the app. That is the collaboration half of the project name.

The repository is a melos monorepo with a sandbox and five examples

The top level listing describes the structure, and melos.yaml at the root says this is a Dart monorepo built with the melos tool.

There is a packages directory, which is where the actual packages live, a sandbox directory, an examples directory, a docs directory with a docs.json file beside it, an assets directory with the logo and the screenshots, and the usual project files, pubspec.yaml, pubspec.lock, analysis_options.yaml and a .pubignore that keeps development-only files out of the published package.

The examples directory is the most informative part, because the five example projects are named after the features they demonstrate. There is a feature_preview example, a full_example, a knobs_example, a monorepo_example and a screen_util_example. Read as a set, they cover the questions a Flutter team asks when it adopts a tool like this: how do you preview a feature in isolation, what does a complete setup look like, how do you expose knobs or properties for tweaking, how does the tool behave in a monorepo, and how do you share a screen across a project.

The knobs example is the one to look at first if you are evaluating the tool, because it is the feature that decides how useful the tool is in practice. A knob is a control that lets you vary a property of a component while you look at it, and without it a widget catalogue is a gallery of frozen states, which is still useful but much less useful than a set of live controls. The screen_util example answers the other practical question, which is what happens when the same widget appears in several screens and you want one definition.

The monorepo example matters too, because a Dart monorepo with melos is how many Flutter teams are organised, and a tool that has an example for that layout has clearly been run in one.

Widgetbook Cloud, golden tests and the visual pull request

The README splits the project into the open-source part and a hosted part called Widgetbook Cloud, and the distinction is the most important thing for anyone evaluating it.

Widgetbook Cloud is described as a managed hosting solution for Widgetbook that allows you to run golden tests to detect and review all UI changes in your pull request, and it is explicitly inspired by Chromatic. The features it lists are four.

Sharing is the first: publish your Widgetbook build for other developers, designers, PMs or clients to reference, so everyone can check that the UI looks right without touching code. The word clients is doing some work there, which tells you the intended audience extends outside the engineering team.

Golden tests are the second, and they are described as zero-configuration visual regression tests run on your widgets across all states, devices, themes and text scale factors, to detect all changes. That list is the interesting part, because text scale factors and themes are exactly the axes on which Flutter interfaces break, and the accessibility angle matters more than usual in a framework where the layout is built by the framework rather than by the developer. Zero configuration is a strong claim, and it is the sort of claim to test on your own project rather than accept.

Visual pull requests are the third, and they are the feature the Chromatic comparison is really about: detecting and reviewing all UI changes inside a pull request, so a reviewer sees a picture of what changed rather than a description.

Figma reviews are the fourth, connecting your Figma designs so you can review your Flutter widget next to the original design. That is the one that pulls designers into the tool rather than showing them something.

There is a free tier, and the README links a sign-up at app.widgetbook.io alongside the cloud documentation. The commercial shape is worth being clear about: the open-source package gives you the sandbox, and the hosted service gives you the continuous review loop, with the free tier as the entry point.

Documentation, demos and how the project explains itself

The README is a signpost rather than a manual, and it points in four directions. There is the website at widgetbook.io, the documentation at docs.widgetbook.io, a hosted demo at demo.widgetbook.io, and the project social accounts, an X account and a YouTube channel.

For the open-source part, the documentation is the setup and install guide in the docs, under the quick start section, and the README's instruction is to follow it rather than to do anything else.

The demos are two videos. The first is a two-minute demo from Google's Flutter team, which is worth watching for a specific reason: it tells you that a team with no relationship to the project thinks the tool is worth demonstrating, and it is the fastest way to see the workflow without installing anything. The second is a one-minute demo of Widgetbook Cloud.

The community channels are a Discord server, an X account and a YouTube channel, and the contribution route is documented too, with a contribution docs page listing the ways to help. The repository has a CONTRIBUTING.md at the root and a .github directory.

The pattern across the whole project is a company that runs an open-source tool and a hosted product on top of it, with the open-source part documented on its own site and the commercial part documented on the same site under a cloud section. That structure has consequences for a reader: the open-source README will describe the sandbox, and anything about visual regression, pull request review or Figma integration lives behind the hosted product's documentation and its sign-up.

The version gap, the licence and the state of the open-source side

The licence is MIT, with the LICENSE file in the repository root and the badge in the README header, and the package is published on pub.dev as widgetbook, which the README links to from the logo block. This describes the published terms rather than legal advice.

The release history is where the picture gets interesting, and it deserves a careful reading rather than a summary. The most recent release in the list is 0.0.11 from 2021-10-13, with 0.0.10 from 2021-10-06 and 0.0.9 from 2021-09-10. Meanwhile the last push to the repository was on 2026-10-13, and the repository is not archived.

So the open-source package's published versions end in 2021 while the source tree is still being worked on in 2026. That gap is a normal shape for a project whose main activity has moved to the hosted product, and the README reflects that shift, since the features it advertises for the open-source side are the sandbox and the catalogue, while the new capabilities, golden tests, visual pull requests and Figma reviews, are all presented under Widgetbook Cloud.

What a team should take from that is a practical one. If you want the sandbox, the question is which version of the package to use, and the answer is to check pub.dev rather than to assume the repository state equals the published state. If you want the continuous review features, the question is whether you are willing to use a hosted service, and the free tier is there to make that answer easy.

The second judgement is about what the tool does not do. Widgetbook is a development and review environment for widgets and screens. It is not a test framework, it is not a design system package, and it does not replace the app. The feature list says it well, implementing components and pages without needing to fuss with data, APIs or business logic, which is the scope, and the rest of the work still happens in the application.

Editorial conclusion

Adopt the open-source Widgetbook when your Flutter team wants a shared place to develop components in isolation and to keep the awkward states written down, since that is the part the MIT licensed package does and does well. It is the wrong tool if you need visual regression testing on pull requests, because that is Widgetbook Cloud and a commercial product with a free tier, and the wrong tool if you want a Flutter implementation that lives in the Flutter ecosystem's own tooling rather than a separate service. Before adopting, check the published package version on pub.dev against the repository activity, since the visible release history ends in 2021 while the repository is still being pushed, and read the setup guide rather than the README for the current install steps.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. widgetbook/widgetbook on GitHub