Widgetbook is an open-source package for organizing and testing Flutter widgets in different scenarios. It provides a safe environment for previewing and testing widgets in various states, improving UI debugging and user experience.
Widgetbook 3 brings forth the power of code generation for automatic use case creation and many new enhancements and improvements. In addition, brand new documentation will help Flutter developers to utilize all features of Widgetbook 3 in detail.
This robust new release introduces innovative features, improved naming conventions, and reduced dependencies. The spotlight is on Addons, allowing customization of use cases, while the dependence on code generation is reduced, with support now limited to use cases only, which highly reduces build_runner times.
Removing all builders except appBuilder, and dependencies like provider, go_router, flutter_bloc, and freezed; Widgetbook 3 offers a cleaner, more user-friendly environment.
In this transition, familiar tools have been renamed or removed. For instance, the @WidgetbookUseCase has evolved into @UseCase, and @WidgetbookApp is replaced with the @App annotation.
Knobs have been redefined with intuitive naming conventions, and the previous categorization system has been replaced with a streamlined ‘directories’ approach.
In the manual approach, you would individually catalog each widget and its variations in the Widgetbook. Although this approach provides excellent flexibility, it can become cumbersome and time-consuming, especially when dealing with many widgets or complex UIs.
On the other hand, the code generation approach introduced in Widgetbook 3 uses annotations to define widgets and their use cases. By running a code generator, you can automatically create a catalog of all annotated widgets in your codebase. This approach is far more efficient, especially for larger projects, as it saves time and reduces the risk of human error.
While both approaches have their merits, this guide will focus on the code generation approach due to its efficiency and productivity advantages.
Let’s begin to learn how Widgetbook 3 is supercharging your Flutter projects.
Kickstart your journey with Widgetbook 3 by adding the necessary dependencies to your pubspec.yaml file:
Next, create the entry point for your Widgetbook application by adding a new widgetbook.dart file in your lib directory. The file namewidgetbook.dart can be changed to anything that you like.
This is a basic implementation of Widgetbook in a Flutter project. The code imports necessary packages and generates a Widgetbook application.
The @App annotation marks the WidgetbookApp class which extends StatelessWidget. The WidgetbookApp’s build method then returns an Widgetbook.material instance. The directories variable, auto-generated by the @App annotation, is passed into Widgetbook.material as an argument, setting up the necessary directories for the Widgetbook app.
This implementation allows developers to preview their widgets in a catalog-like structure, promoting easy accessibility and reusability of components.
Directories are a list of folders, components, and use cases. Generator creates the directories variable automatically.
Remember that you can create a Widgetbook entry point in your existing app or create a new independent one.
In Figma, components are reusable UI elements that can have multiple variants. For consistency, in Widgetbook, Widgets are referred to as components.
Widgetbook follows a component and use-case approach, with a single component having one or multiple use cases. A use-case can be a variant of a component or represent a specific component state.
Developers use a folder tree structure to organize and catalog components in Widgetbook.
Widgetbook 3's power lies in its ability to generate use cases through annotations. Let’s take an example of a CustomButton widget:
The @widgetbook.UseCase annotation in Widgetbook defines a specific use-case scenario for a particular widget. It acts as a marker for the Widgetbook tool to generate a code snippet showing the specified widget in the designated scenario.
In the context of @widgetbook.UseCase(name: 'Enabled', type: CustomButton,):
Once you have set up the annotations for your widgets, you can run the code generator:
You’ll see widgetbook.directories.g.dart file is now generated right next to the entry point file widgetbook.dart that you have created.
If you follow a manual approach, you will write this file all on your own. As you can see, the generator approach simplifies the process a lot.
Note that this file is imported to the entry point `widgetbook.dart`
Widgetbook supports Flutter Desktop and Web. To start exploring your widgets in Widgetbook, run the following command:
You can change chrome with your Desktop of choice, macos , linux or windows . Next, you’ll be able to see your catalogs.
Addons in Widgetbook offer a flexible way to customize your components' presentation. You can use them to apply themes, adjust text scales, select different locales, and emulate different device frames, among other functionalities.
Let’s consider a simplified example where you will use the MaterialThemeAddon and DeviceFrameAddon in your Widgetbook:
In this example, we’ve used the MaterialThemeAddon to add two themes, light and dark, to your Widgetbook.
The DeviceFrameAddon lets us preview your widgets on different device frames like the iPhone SE and iPhone 13.
You can see how device selection works below in action:
This way, addons help you tweak your components’ presentation in the Widgetbook interface, enhancing your widget testing and previewing experience.
Now let’s take a look at build-in Addons such as MaterialThemeAddon, TextScaleAddon, LocalizationAddon, and DeviceFrameAddon in Widgetbook.
The provided example showcases the diverse application of Addons in Widgetbook. It includes the utilization of MaterialThemeAddon, TextScaleAddon, LocalizationAddon, and DeviceFrameAddon. While you have these Addons, you can still create your custom Addons and integrate them into your widget tree. Learn more about Addons on the documentation website.
The Widgetbook’s Addon system is structured to boost flexibility, ensure smooth interoperability, and enrich the overall user experience. Developers can discover new avenues and enhance their development process efficiency by mastering and adeptly applying this system.
Knobs are interactive tools that allow you to dynamically adjust the properties of your widget directly from the Widgetbook UI. They facilitate understanding how the widget behaves under different conditions, which can aid developers and designers in making robust and well-rounded component designs.
Now, let’s look at an example of a custom button with two states: enabled and disabled. Let’s add a new use case to use Knobs.
In the enabled state, the button is clickable, and in the disabled state, it’s not. We’ll utilize knobs to change the title of the button and its state.
First, Let’s review CustomButton widget that you have created already:
Now, let’s explain the Widgetbook use case with knobs for the CustomButton Widget:
In the above use case, we’ve added two knobs:
This way, knobs provide a quick and easy way to test and document different states and behaviors of a widget.
Make sure to run build_runner and also run the project.
Widgetbook Cloud takes the utility of Widgetbook to a new level by facilitating seamless collaboration among your entire product team.
While Widgetbook assists Flutter developers in efficiently creating, testing, and cataloging widgets, Widgetbook Cloud extends this functionality, simplifying the review and feedback process.
It enables sharing widgets with designers, project managers, clients, and other stakeholders, streamlining communication and fostering more cohesive and efficient product development.
Key Features of Widgetbook Cloud:
Today, you can get early access to Widgetbook Cloud. Check out the website for more information.
In conclusion, Widgetbook 3 is an open-source package for Flutter developers, enhancing the widget development process, testing, and documentation. With catalogs, developers can organize components efficiently.
Use cases facilitate easy testing and sharing of different widget states, while addons enable customization of the development environment. The software’s adaptability to various themes, text scales, locales, and device frames offers an integrated and robust testing interface.
Widgetbook Cloud revolutionizes how teams collaborate, providing a unified platform to review, discuss, and enhance Flutter widgets. Whether you’re a developer looking for precise feedback or a designer striving for pixel-perfect implementation, Widgetbook Cloud covers you.
You can explore the available addons, knobs, and Widgetbook Cloud and how to use them in the Widgetbook documentation. Remember that you can join the Widgetbook Discord server to discuss, learn more and talk to us to receive support.