About Salto

Salto Systems is a global leader in smart access solutions, offering cutting-edge IoT technology for secure, cloud-based access control. With over 40,000 clients and a presence in more than 40 countries, Salto powers seamless and secure entry experiences for hospitals, offices, universities, and more. Their innovative platform integrates mobile access, wireless locks, and real-time management — all designed to simplify access control in a connected world.

In 2022, Salto made the strategic decision to switch to Flutter to unify their codebase, accelerate development, and improve cross-platform performance. Since then, they’ve successfully built seven production apps in Flutter, making it a core part of their mobile development strategy.

Challenge: Catching UI Changes Early

With seven different Flutter apps in production, Salto’s developers are committed to delivering a consistent and high-quality user experience. However, updating a widget in one part of the app often had unexpected side effects elsewhere — leading to UI overflows, visual bugs, or accessibility issues that were hard to detect early.

To catch these regressions in advance, the team relied on Flutter’s snapshot-based golden tests.

“We used Alchemist for golden tests, but generating consistent snapshots across different machines was difficult and didn’t integrate smoothly into our GitLab workflow. When something broke, it often took a long time to fix UI issues and stabilize the CI pipeline.” — Arthur Schenk, Mobile Team Lead at Salto

Solution: How Widgetbook Transformed Salto’s Workflow

Building Widgets in Isolation

While exploring ways to streamline UI reviews and catch visual bugs earlier, Salto’s mobile team discovered Widgetbook. They initially adopted the open-source version to accelerate Flutter UI development and quickly saw the benefits.

“We build new features by starting with Widgetbook, allowing us to immediately develop the UI in isolation and see how new components behave. Building in isolation is especially helpful for larger components and screens that handle various data states — like loading, loaded, or error. Before Widgetbook, testing error states was time-consuming because they’re naturally hard to reproduce; the data often comes from sources we can’t easily control. But with Widgetbook’s isolation-first approach, we can inject mocked data and test all component states. Once a component is ready, other developers can easily explore its different variations.” — Arthur

A Central Overview of All Widgets

To maintain visibility across their growing UI ecosystem, Salto created a shared Widgetbook for common components, along with seven app-specific Widgetbooks — one for each app’s unique widgets and screens.

“The UI team is happy they now have a clear overview. They can quickly explore components and screens in different states, themes, and device sizes — all in one place.” — Arthur

This setup not only improved collaboration between designers and developers but also made it easier to ensure visual consistency across all Flutter apps.

Catching All UI changes with Widgetbook Cloud

After seeing the benefits of the open-source Widgetbook for local widget development, Salto wanted to extend this workflow to their entire CI process. To do so, they scheduled a demo with Widgetbook to explore how Widgetbook Cloud — the fully integrated, cloud-based review platform — could support them.

“Onboarding was smooth and easy to set up, especially thanks to the dedicated Slack channel where we could quickly resolve any issues” — Arthur

Although Widgetbook Cloud was initially used primarily by developers, Salto has recently expanded its use to include both QA and design teams, creating a more collaborative and efficient review process.

“Widgetbook is integrated and running in our build CI pipelines. So, every merge request triggers Widgetbook Builds to run the snapshot tests. If we made changes in code, Widgetbook shows which components stayed the same and which components had visual adjustments making it trivial to review visual changes and get the code merged.” — Arthur

Salto configured Widgetbook Cloud to test all widgets automatically for their light and dark theme and for a normal and enlarged text scale factor. “Testing in different configurations helps us to see the changes for our themes. Specifically, with the keychain, there was a lot of inconsistency in dark mode. Widgetbook Cloud helped us to find these inconsistencies efficiently and resolve the theming issue right away. In addition, many problems have been detected and fixed while the merge requests were still open. Otherwise, the problems would have shipped to our staging environment and would have been raised by QA causing time consuming iteration cycles. With Widgetbook you can see that at once. The entire team is very satisfied because it is so handy and saves time.”

“Widgetbook saves us a lot of time and provides valuable insight into which changes are made with each merge request. This prevents problems in the UI, and our workflow became certainly twice as fast.” — Arthur

If this sounds like an outcome your team could also benefit from, try Widgetbook for free or contact our team to learn more.

Big thanks to the Salto team for the great collaboration on this case study — especially to Arthur Schenk. It was a pleasure working together! 💙

How Salto prevents UI problems while saving 50% of their time with Widgetbook was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

What is Widgetbook?

Flutter teams typically work with design systems created by freelancers or in-house design teams. While Figma’s component-based approach naturally generates a comprehensive catalog through best practices, Flutter developers face challenges after implementing these components as Widgets and collecting feedback on the adjusted or added Widgets. The traditional approach of sharing screenshots via Slack or Teams for assessment proves inefficient and cumbersome.

Widgetbook revolutionizes this workflow by providing a specialized environment for component visualization and testing. Through its comprehensive feature set, teams can:

• Efficiently preview and test widgets in isolation and with different hard-to-reach states
• Ensure consistent behavior across different devices and themes
• Rapidly iterate on components with hot reload support
• Seamlessly integrate UI testing into existing Flutter projects

By implementing this structured approach to component management, teams eliminate the need for ad-hoc testing and screenshot sharing, significantly enhancing development efficiency and team collaboration.

What is Widgetbook Cloud?

Widgetbook Cloud streamlines UI component development through a collaborative platform. Key features include:

• Real-time team collaboration for instant component review
• Automated visual regression testing to detect UI changes
• Component version control with rollback capabilities
• Efficient review workflow with comments and approvals

The platform accelerates the design-to-development cycle by enabling direct component interaction in a dedicated environment.

Built-in automated testing maintains UI consistency while reducing manual QA effort, allowing teams to prioritize innovation.

Strategies

Design systems consist of core components that serve as building blocks for complex components and screens. While Widgetbook offers the most value with 100% component coverage, sprint time constraints often limit implementation capacity. To maximize Widgetbook’s benefits during the migration phase, consider the following approaches based on your goals.

Core Components

When redesigning core components, Widgetbook excels at tracking changes and improving team communication. This approach maintains team alignment and prevents regressions across your application. Since core components are frequently reused, prioritize cataloging them first. This strategy maximizes the benefits for your team by establishing a solid foundation for component management.

New Components

When expanding your application’s feature set, new components are naturally introduced. These features and components typically undergo multiple iterations, making them ideal candidates for Widgetbook integration. This ensures design consistency and implementation accuracy throughout the process of optimizing your solution to meet customer requirements.

The two approaches can be mixed depending on your goals while migrating all your components to Widgetbook.

Widgetbook Entries Generator

Our partner LeanCode, a leading Flutter development agency, specializing in enterprise applications, has developed an automation tool that streamlines the integration of existing widgets into Widgetbook. This Widgetbook Entries Generator efficiently scans your codebase and generates the necessary Widgetbook code, significantly reducing manual implementation effort.

During their extensive work on Flutter projects, LeanCode identified a critical challenge: manually creating use cases for existing widgets was time-intensive and prone to errors. Drawing from their experience, they developed the Widgetbook Entry Generator to optimize the migration process.

Key benefits of the entries generator include:

• Automated generation of boilerplate code for rapid widget integration
• Enhanced accuracy through automated processing
• Streamlined adoption of Widgetbook’s testing and collaboration features

Widgetbook entries generator is available for VS Code.

Example project

Let’s explore the widgetbook-explained repository, which contains a simple grocery shopping app, as our example project.

The project structure is as following

.
├── lib      ⬅️ groceries_app
│   ├── app.dart
│   ├── features
│   ├── ... (omitted folders and files)
│   └── ui
│       ├── ui.dart
│       └── widgets
│           ├── app_bar.dart
│           ├── bottom_navigation_bar.dart
│           ├── card.dart
│           ├── counter.dart
│           ├── divider.dart
│           ├── empty_state.dart
│           ├── icon.dart
│           ├── icon_button.dart
│           ├── navigation_item.dart
│           ├── page_shell.dart
│           ├── primary_button.dart
│           ├── responsive_layout.dart
│           └── widgets.dart
├── pubspec.yaml
└── widgetbook      ⬅️ widgetbook_workspace
    ├── README.md
    ├── analysis_options.yaml
    ├── lib
    └── pubspec.yaml

Settings

Before the generator can be used, make sure to configure the settings of the extension.

Barrel File import

.
├── lib      ⬅️ groceries_app
│   ├── app.dart
│   ├── features
│   ├── ... (omitted folders and files)
│   └── ui
│       ├── ui.dart     🔥 Barrel file import
│       └── widgets
│           ├── (ommited files)
│           └── widgets.dart
├── pubspec.yaml
└── widgetbook      ⬅️ widgetbook_workspace
    ├── README.md
    ├── analysis_options.yaml
    ├── lib
    └── pubspec.yaml

Due to the file structure, we configure the Barrel File import as package:groceries_app/ui/ui.dart, which exports all Widgets from the production app.

Root directory name

After cloning the repository widgetbook-explained, we set the Root directory name to match widgetbook-explained.

Widgets directory path

This setting specifies the generation target for Widgetbook files.

.
├── lib      ⬅️ groceries_app
│   └── ... (omitted folders and files)
├── pubspec.yaml
└── widgetbook      ⬅️ widgetbook_workspace
    ├── README.md
    ├── analysis_options.yaml
    ├── lib     🔥 Where we want the generated files
    └── pubspec.yaml

We set the path to /widgetbook/lib to generate files in the ./widgetbook/lib directory.

How to genenerate a use-case for a Widget?

To generate a Widgetbook entry, open the PrimaryButton file, access the Quick Fix menu, and select "Create widgetbook entry for this widget".

Widgetbook entry generator creates the following code

import 'package:flutter/widgets.dart';
import 'package:groceries_app/ui/ui.dart';
import 'package:widgetbook/widgetbook.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;

@widgetbook.UseCase(
  name: 'default',
  type: PrimaryButton,
)
Widget useCasePrimaryButton(BuildContext context) {
  return PrimaryButton(
    content: context.knobs.string(label: 'Content', initialValue: 'Content'),
    leading: const SizedBox.shrink(),
    trailing: const SizedBox.shrink(),
  );
}

The generated code is a functional Widgetbook use-case that serves as a starting point for further customization.

Developers can enhance the use-case by adding specific implementations, such as customizing the leading and trailing properties with icons.

Generate use-cases for multiple Widgets

Besides generating use-cases for individual widgets, the Widgetbook entry generator can create use-cases for an entire folder at once.

To use this feature, simply right-click on a folder in the file explorer and select the generate option.

Which will result in the following 20 generated files for Widgetbook.

.
├── lib      ⬅️ groceries_app
│   └── ... (omitted folders and files)
├── pubspec.yaml
└── widgetbook
    ├── lib     🔥 Generated files are located here
    │   ├── about
    │   │   └── about_screen.dart
    │   ├── app_bar.dart
    │   ├── app_theme.dart
    │   ├── bottom_navigation_bar.dart
    │   ├── card.dart
    │   ├── counter.dart
    │   ├── divider.dart
    │   ├── empty_state.dart
    │   ├── features
    │   │   ├── basket
    │   │   │   ├── views
    │   │   │   │   └── basket_view.dart
    │   │   │   └── widgets
    │   │   │       ├── basket_card.dart
    │   │   │       ├── cost_item_row.dart
    │   │   │       └── summary.dart
    │   │   └── utility
    │   │       └── placeholder.dart
    │   ├── icon.dart
    │   ├── icon_button.dart
    │   ├── main.dart
    │   ├── main.directories.g.dart
    │   ├── navigation_item.dart
    │   ├── page_shell.dart
    │   └── primary_button.dart
    └── pubspec.yaml

Of the 20 generated files 6 showed missing data for properties of type IconData which were fixed within a minute.

Conclusion

The Widgetbook entries generator significantly accelerates the integration of existing Flutter widgets into Widgetbook. By automating the creation of use-cases, teams can quickly build a comprehensive widget catalog without disrupting their development workflow. This tool, combined with Widgetbook’s testing capabilities, enables teams to maintain high-quality component libraries while focusing on delivering value to their customers.

Whether you choose to migrate core components, new features, or use the automated generator, Widgetbook provides the flexibility to adopt a testing strategy that fits your team’s needs. This structured approach to widget management ensures consistent design implementation and efficient team collaboration throughout your project’s lifecycle.

Create use-cases for Widgetbook: Strategies and Automation Tools was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

flaconi has been the leading German e-commerce shop for fragrances and beauty products for the past years. Reaching their customers via webshop and mobile app comes with interesting design challenges. At the heart of flaconi’s design prowess lies Figma and the Style Dictionary API, enabling them to propagate design excellence throughout the company. Design tokens serve as the foundational elements for colors, fonts, and more, forming the backbone of their design system. From this foundation, they craft components for web, mobile, and also marketing material. Leveraging Storybook for the web and Widgetbook for mobile ensures that all components are accessible for designers and developers. A clear commitment to developing mobile applications with Flutter ensures efficiency gains as a single code base can be used to develop for Android and IOs.

Widgetbook fits perfectly into this tech stack as a Flutter first tool. Before Widgetbook became part of flaconis development workflow, flaconi encountered potential for optimization in their internal processes related to testing and presenting UI components. Despite having a design system in place, the absence of a dedicated tool posed difficulties in ensuring the seamless functionality of basic elements, such as buttons in their mobile app. Prior to Widgetbook, flaconi’s designers had to navigate a complex process of manually testing components, relying on hardware and test apps. This not only consumed a significant amount of time but also presented difficulties in ensuring the consistent performance of elements across various screen orientations and text scales. The absence of a unified tool added complexity to the review process, necessitating extensive coordination between designers and developers. Widgetbook emerged as a solution, streamlining flaconi’s UI design and testing procedures, ultimately enhancing their workflow efficiency.

Widgetbook aligns Developers and Designers

Let’s delve deeper into how Widgetbook has not only streamlined the exchange of information but also elevated the entire process of showcasing and testing components for flaconi. Despite already having a robust design system in place, flaconi recognized opportunities for optimizing the testing and presentation of UI components within their mobile app team. The introduction of Widgetbook offered a refined solution, allowing flaconi’s product team to effortlessly isolate and test fundamental components, such as buttons, across diverse scenarios — from various screen orientations to different text scales. Widgetbook plays its role in eliminating the need for separate builds, significantly boosting the efficiency of UI element testing. The tool is especially valuable in addressing accessibility scenarios, showcasing its broader impact on enhancing overall design and testing processes at flaconi.

Imagine this scenario: an app is to be translated and the UI must be able to function not only with a Latin alphabet but also with Arabic characters. Widgetbook empowers designers and QA testers to explore various cases seamlessly, bypassing traditional hurdles like creating test apps or constantly adjusting phone settings. This marks a paradigm shift, ensuring components exhibit the desired behavior without unexpected glitches, ultimately contributing to a smoother and more effective design and testing experience for flaconi.

Ensure Accessibility

flaconi’s commitment to ensuring accessibility in their app takes a significant stride forward with the integration of Widgetbook into their testing processes. As part of the many ways to test UI with Widgetbook. It is possible to create scenarios in which you test your UI components for accessibility in a dedicated way. flaconi’s product team uses the Widgetbook dashboard to thoroughly test components under diverse conditions. This includes evaluating how the UI elements respond to changes in text scale and ensuring optimal functionality for users with disabilities. The platform’s user-friendly interface allows designers to simulate settings directly from the Widgetbook dashboard, eliminating the need for complex, manual testing procedures. This makes the tedious clicking around in the test app settings to display different accessibility settings obsolete and saves time and nerves.

“At flaconi, Widgetbook is our go-to for testing mobile UI design. It’s changed the game, allowing us to showcase and test components effortlessly. No need for dedicated builds — Widgetbook simplifies testing scale factors and ensures accessibility with unparalleled ease.” — Mohammed Almissbah (Senior Mobile Engineer at flaconi)

We encourage others to explore Widgetbook’s transformative capabilities in streamlining collaboration and ensuring a user-friendly experience. Embrace the future of UI design with Widgetbook. Big thanks to Mohammed Almissbah and flaconi for sharing their invaluable insights, driving positive change in digital design.

Case Study: How flaconi covers UI testing with Widgetbook was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

Styling Material Widgets can be tricky. Using the widgetbook_base_components mason brick you can get an overview inside Widgetbook how they will look, feel and behave

Struggling with styling ThemeData

Personally I am a big fan of using the default Material Widgets in Flutter Apps as they are easy to use, offer great support for Accessibility and relying on theme is great if you are onboarding new team members as they can just use the default blocks without having to make sure they use the correct widget.

However one big caveat with this can be what Mike Rydstrom put into great words during his workshop at Flutter & Friends (Material for the Workshop can be found here)

Flutter Material theming is fun and easy — but tedious

This really resonated with me as that basically reflects my experience with it. Adjusting ThemeData to match a given Design or just to your preference can indeed be tricky to get all the nuances right. However things like Mike’s Theme Playground and flex_color_scheme can really help you nail your ThemeData. When you have your Theme just right and you are able to just use Material Widgets without having to do custom styling when using them it feels great to use, is quick and ensures visual consistency between your uses of these Widgets.

The idea

widgetbook_base_components is a mason brick that generates UseCases for your Widgetbook to show you how these widgets would appear and behave in your App.

In the first version the following components are supported: Buttons, TextStyles, Controls, Card, AlertDialog, Indicators, Chips, TextFields, ListTile, BottomNavigationBar

You might notice that these UseCases in Widgetbook have a lot more info than you are normally used to. This is because the idea behind widgetbook_base_components is to get a quick overview of how certain Material Widget Groups like buttons/switches/etc behave if used in an app only relying on the style set by the encapsulting ThemeData.

For some examples you can also check out a Widgetbook with these components here:

https://abausg.github.io/bricks/widgetbook_base_components/web/

Using the brick

Note: I am assuming you already have setup Widgetbook in your project. If not check out the official documentation https://docs.widgetbook.io/

1. Follow the installation steps for mason if you haven’t by running
   dart pub global activate mason_cli
   mason init
2. Add the widgetbook_base_components brick using
   mason add widgetbook_base_components
3. "Make" the brick using mason make widgetbook_base_components
4. Run dart run build_runner build (ignore this if you are using watch )
5. Check your Widgetbook for the new Base Components 🎉

Next Steps

I think seeing the different Variants side by side offers a great way of grasping how your App might look for the provided ThemeData

I am well aware that this is only a small subset of Material Widgets that are supported but I think it is a great start. If you are missing a specific Widget feel free to open a PR.

For thoughts or any more questions reach out to me on X/Twitter

Thanks

Many thanks to Roaa, Lucas and Tim from Widgetbook for the Feedback on the Brick.

Also big thanks to Mike! His work for everything Material is phenomenal and his Theme Playground was a huge inspiration for this. You should follow him on X/Twitter to always get the latest news about Material and Flutter!

JavaScript is not available.

Code for the Brick:

https://github.com/ABausG/bricks/tree/main/bricks/widgetbook_base_components

Example of the Widgetbook:

https://abausg.github.io/bricks/widgetbook_base_components/web/

Getting Material Base Components into Widgetbook was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

October 2023 was a landmark month for Widgetbook, thanks to the collective efforts during Hacktoberfest. This year, we witnessed an outpouring of contributions, leading to groundbreaking features and enhancements in Widgetbook’s package and CLI. Let’s delve into these exciting developments, highlighting specific changes and the community’s incredible contributions.

Hacktoberfest in Statistics

The Hacktoberfest 2023 campaign at Widgetbook was not just an event but a vibrant showcase of collective effort and technical prowess. Let’s delve into the heart of this success through some impressive statistics and acknowledge the stars behind these achievements.

Impressive Contributions:

• Total Pull Requests (PRs): We received a remarkable count of 17 PRs.
• New Contributors: These PRs were contributed by 10 enthusiastic developers.
• Diverse Contributions: The range of contributions spanned from UI enhancements to CLI optimizations, reflecting the diverse skill set of our community.

For a detailed look at all the PRs, visit Widgetbook’s Hacktoberfest Contributions.

Shoutout to Our Outstanding Contributors

Each contributor brought unique ideas and expertise, significantly enhancing Widgetbook’s capabilities.

• @Mastersam07: Showcased exceptional professionalism with 3 addons, 2 knobs, and crucial mobile support. His PRs were a benchmark in code quality and documentation.
• @geisterfurz007: Made a rare and valuable contribution affecting widgetbook_generator, a less common area during Hacktoberfest.
• @francescovallone: Added the complex and multifaceted color knob. His PR, rich in review comments, exhibited his patience and openness to iterative changes.
• @daohoangson: Displayed remarkable patience with a PR that, although not merged, was accepted for its value during the discussion phase.
• @logickoder: Successfully tackled the daunting task of adding a knob for DateTime, a notoriously complex data type.
• @07Abhinavkapoor: Played a pivotal role in introducing the light theme, illuminating Widgetbook’s interface.
• @boredcity: Enhanced the user experience by adding a new q query parameter for the navigation bar’s search functionality.

Each contributor has added value to Widgetbook and inspired the community with dedication and skill. We extend our heartfelt gratitude to them and to every individual who participated, making Hacktoberfest 2023 a memorable and productive event for Widgetbook.

As promised, all our contributors will soon receive their swag box, including the Widgetbook T-shirt.

You can read more in detail on our GitHub issues.

Widgetbook 3.4: What’s New

The release of Widgetbook 3.4 brings a host of exciting new features and improvements, enhancing both the developer’s experience and the end-user interface. Here’s what’s new:

New Knobs

• DateTime Knob: Tackling one of the most complex data types, the DateTime knob offers intuitive date and time manipulation within the Widgetbook interface.

context.knobs.dateTimeOrNull(
  initialValue: initialDate,
  label: 'Select Date Time',
  start: DateTime(initialDate.year - 1),
  end: DateTime(initialDate.year + 1),
)

• Duration Knob: This knob allows for the adjustment of duration values, adding another layer of interactivity.

context.knobs.duration(
    label: 'Increment duration',
    initialValue: const Duration(seconds: 5),
  )

• Int Knob: A straightforward way to adjust integer values directly from the UI.

context.knobs.int.input(
  label: 'Int - Input',
  initialValue: 1,
)

context.knobs.int.slider(
  label: 'Int - Slider',
  initialValue: 2,
)

• Enhanced Color Knob: The color knob has been revamped to support various color spaces and opacity levels, including a nullable version for more versatility.

context.knobs.color(
  label: 'Color',
  initialValue: Colors.blue,
)

Explore Knobs in Detail

Interface Improvements

• Light Theme: The introduction of a light theme option caters to different aesthetic preferences

• WidgetbookLeafComponent: Simplifying components’ organization with a single use case enhances the navigation experience.

• Mobile support The mobile support has landed on the Widgetbook UI.

New Addons

Widgetbook 3.4 introduces several new addons, each designed to augment the functionality of Widgetbook and enrich the developer’s toolkit. These addons offer diverse capabilities, from improving accessibility to providing detailed insights into widget properties. Here’s an overview of these innovative additions:

1. Zoom Addon: The Zoom Addon provides a seamless way to adjust the zoom level of widgets within the Workbench. This feature is handy for fine-tuning the appearance and layout of widgets. Learn More About the Zoom Addon

ZoomAddon(initialZoom: 1.0)

2. Grid Addon: With the Grid Addon, developers can overlay a pixel grid on the previewed use case. This is invaluable for ensuring alignment and consistency in design. Explore the Grid Addon

GridAddon()

3. Accessibility Addon: This addon is a powerful tool for detecting and resolving accessibility issues. It leverages the accessibility_tools package to ensure that widgets are accessible to all users. More on Accessibility Addon

AccessibilityAddon()

4. Inspector Addon: The Inspector Addon is an essential tool for developers, offering the ability to inspect various widget properties, such as colors, sizes, and padding. This feature enhances the debugging and design process within the Widgetbook’s Workbench. Discover the Inspector Addon

These addons make Widgetbook more versatile and user-friendly, offering developers enhanced capabilities to build and test their widgets more effectively.

Enhancements in Generator Version 3.3.0

The Widgetbook Generator also saw significant enhancements in version 3.3.0, making it more powerful and user-friendly. Key updates include:

• Custom Path for @UseCase: This feature allows developers to specify a custom path for their use cases, improving organization and readability.

@widgetbook.UseCase(
  name: 'Example',
  type: YourWidget,
  path: '[Category]/folder',
)

• Support for WidgetbookLeafComponent: This addition streamlines the navigation for components with a single use case, simplifying the user interface and making it more intuitive.
• Discover More on Generator 3.3.0 Enhancements

Upgrade your Widgetbook today and look for new features on our demo project.

dependencies:
  widgetbook: ^3.4.0
  widgetbook_annotation: ^3.1.0

dev_dependencies:
  widgetbook_generator: ^3.3.0

Conclusion

October was a month of growth, learning, and community spirit for Widgetbook. The contributions we received enriched our open-source package and exemplified the spirit of collaboration and innovation that drives the tech world forward.

As we release version 3.4, we extend our heartfelt thanks to every contributor who made this possible. Here’s to many more successful Hacktoberfests!

Widgetbook x Hacktoberfest 2023 was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

Key takeaways

- Widgetbook is a generated UI component library inspired by Storybook.js

- Usually it is costly for small projects to maintain a UI component library

- Using Widgetbook in your tests makes it maintenance cost of your UI component library low

(original article link)

Hi, my name is Bas de Vaan, Flutter Developer for Dutch Coding Company. I started developing mobile apps about 10 years ago, and while I’ve done a lot of stuff since that time, always had a love for developing for mobile. Such a nice platform with quick feedback and clear boundaries. ❤

Recently, I was inspired by a talk from Lucas about Widgetbook. This inspired me to try using Widgetbook in our current projects, while minimising the amount of new code and keeping maintenance costs to a minimum. In this blog post, I will share the approach I came up with.

Widgetbook is a UI component library inspired by Storybook.js. It provides a clear folder structure to display various UI components. These components are generated from your actual code, so you can see how they look in your application. The component library is interactive, allowing you to test the behavior of elements to user input, hover, and click. You can also provide different variations and options for your components to make it clear which variants of your elements are usable. You can host this library online to share it with clients, other developers, and designers. If you want to see the potential of a widget book, checkout their online demo here!

The struggle of maintaining a component library

I recall attending a Javascript meetup and listening to a talk about Storybook. I thought, ‘This would be great to have in Flutter!’ Months later, to my surprise, it actually exists! At a Flutter meetup, Lucas from Widgetbook gave a fantastic presentation about the tool. Its usage seemed easy and promising, with potential in upcoming features. However, the only issue I struggled with was its maintenance cost. For each entry in Widgetbook, you have to define a use case and maintain any changes to your widgets. Here’s an example of how to define a use case in Widgetbook:

@widgetbook.UseCase(name: 'with no text', type: TestFieldWidget)
Widget noTextTestFieldWidget(BuildContext _) {
  return const TestFieldWidget(text: '');
}

So while this use case is pretty small, you can imagine if you have a widget with a lot of options this get very cumbersome. This is an example of a bigger widget (still just a simple checkbox):

@UseCase(name: 'basic', type: CheckboxInput)
Widget basicCheckboxInput(BuildContext context, {bool initialValue = false}) {
  return CheckboxInput(
    field: CheckBoxFieldType(
      name: 'checkbox',
      value: context.knobsOrMock.boolean(label: 'checkboxValue', initialValue: initialValue),
      type: FieldType.bulletin,
      label: context.knobsOrMock.string(
        label: 'CheckboxLabel',
        initialValue: 'checkbox',
      ),
    ),
    onChanged: (bool? changed) {
      initialValue = changed ?? false;
    },
  );
}

So you get the gist. To display each element in your Widgetbook, you need to create a function and annotate it as a use case. Fortunately, the Widgetbook code generation tool performs the rest of the magic for you 🔮.

However, obtaining a Widgetbook using this method felt like more work than I was willing to put in. Ideally, I would like to do as little work as possible. This is what led me to the idea of incorporating it with my widget testing.

Combining widgets with testing

I already have a robust widget testing setup in most of my applications. We use both Widget testing and Golden Testing to test the behavior, look, and feel of our widgets. Whenever there is a change, we see the impact reflected in our tests, giving us more confidence in developing new features. If a change in one place has an unintended effect on another widget, our tests turn red and alert us to the unwanted side effect. If you’re not already testing your widgets, I highly recommend giving it a try! Golden Tests are low in maintenance cost and feel like low effort for a high reward.

What do these tests have in common with the use cases used by Widgetbook? In both cases, you need to build the widget you want, isolate it from the rest of the application, and provide it to a framework, whether it be Widgetbook’s or your testing library’s. This led me to look for a way to combine the use cases of Widgetbook with my tests, and I found a ‘mostly’ working solution!

By just putting the use case functions in the test file itself you can use these functions in your test and annotate them as well. A simple test can look something like this:

@widgetbook.UseCase(name: 'with a lot of text', type: TestFieldWidget)
Widget longTextTestFieldWidget(BuildContext _) {
  return const TestFieldWidget(text: 'A very long test to create a certain amount of text to see how it looks like.');
}

@widgetbook.UseCase(name: 'with no text', type: TestFieldWidget)
Widget noTextTestFieldWidget(BuildContext _) {
  return const TestFieldWidget(text: '');
}

void main() {
  testWidgets(
    "test description",
    (WidgetTester tester) async {
      Widget widget = Builder(builder: ((context) => longTextTestFieldWidget(context)));
      await tester.pumpWidget(widget);
      expect(
          find.text('A very long test to create a certain amount of text to see how it looks like.'), findsOneWidget);
    },
  );
}

It is also possible to provide the initial value of a knob in the function as an optional parameter; this makes it possible to also use the ‘knobs’ in your test. A test for the checkbox that I run in a actual project looks like this:

@UseCase(name: 'basic', type: CheckboxInput)
Widget basicCheckboxInput(BuildContext context, {bool initialValue = false}) {
  return CheckboxInput(
    field: CheckBoxFieldType(
      name: 'checkbox',
      value: context.knobsOrMock.boolean(label: 'checkboxValue', initialValue: initialValue),
      type: FieldType.bulletin,
      label: context.knobsOrMock.string(
        label: 'CheckboxLabel',
        initialValue: 'checkbox',
      ),
    ),
    onChanged: (bool? changed) {
      initialValue = changed ?? false;
    },
  );
}

void main() {
  group('Checkbox Input Golden Test', () {
    GoldenPumpingCompanion companion = defaultPumpingCompanion();

    goldenTest(
      'renders correctly',
      fileName: 'checkbox_input_golden_test',
      pumpWidget: companion.pumpWidget,
      builder: () => companion.buildTestGroup(
        'default widget',
        UseCaseWrapper.wrap((context) => basicCheckboxInput(context, initialValue: false)),
      ),
    );

    goldenTest(
      'renders correctly',
      fileName: 'checkbox_input_checked_golden_test',
      pumpWidget: companion.pumpWidget,
      builder: () => companion.buildTestGroup(
        'default widget',
        UseCaseWrapper.wrap((context) => basicCheckboxInput(context, initialValue: true)),
      ),
    );
  });
}

Please keep in mind that I have some extra test helpers and functions here to assist me in building my tests. This way, even a “complicated” widget test appears clean and moreover provides us with both snapshot tests and an entry in our Widgetbook! Check out my GitHub repository if you’re looking for a simple example project.

Implementing the solution

Okay, I have to confess something. When I said I found a ‘mostly’ working solution, I actually meant that it doesn’t work yet. The code generation of the Widgetbook library cannot correctly handle imports from the test and lib folders. You can fix this by manually adjusting the imports in the file generated by Widgetbook. Remove the imports that start with asset: and replace them with actual imports from your project. This will enable Widgetbook to run, but I don’t like making manual changes to generated code. This is especially problematic since it hinders automated deployment of Widgetbook through a pipeline. When I discovered this, I opened an issue about this problem in the Widgetbook Github repository.

I wrote this blog while I was at Fluttercon 2023 (read more about it in my previous blog). At the conference, I had the opportunity to listen to a talk about Widgetbook and check out their booth. The guys from Widgetbook were also in attendance. During the conference, I came up with a possible solution to the problem.

I had the opportunity to discuss my fix and issue with the developers, who were very open and friendly in their collaboration. Overall, it was a great experience 🙂

While in the progress of writing and publishing this blogpost, Youssef (pictured on the right) actually used my pull request as inspiration and made a fix for Widgetbook!

So soon in a new release (or in the git ref) you could try this test setup for yourself! Awesome! 🚀

EDIT: On the 18th of August, this feature got released in Widgetbook Generator 3.1.0! So update to the latest version and check it out!

Wrapping up

Regarding the future of Widgetbook, version 3 has recently been released, which includes many new features and a fully-fledged cloud environment. Therefore, adopting and implementing Widgetbook now seems like a good idea, especially for apps with a large assortment of UI elements.

If you want to know more about how we implemented Widgetbook at Dutch Coding Company or my views on the future of Widgetbook, feel free to send me a message on Twitter/X (@Bassiuz). I love to discuss all things Flutter :)

How to transform your widget testing setup into a widget library with Widgetbook was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.