Disclaimer: This article is about Widgetbook 2.0 Parts of the content may be out of date.

‍

If you’re into Flutter development for some time then I’m sure you must have heard about WidgetBook at some point. But do you know what actually is a WidgetBook and why do you need it?

In this blog, I’m gonna walk through all of the terminologies along with the practical example. So without further a do, let’s get started 😉

‍

1. Why do you need WidgetBook?

Before understanding what WidgetBook is, let’s first discuss the current scenario in the Software development industry to better figure out why do you need WidgetBook.🤔

Suppose you’ve to build one application in Flutter💙 Normally, all of the designs will come in Figma to the developer. And then you start making the app by following the Figma designs and you basically copy each and every single attribute of design from Figma to Flutter. And then you submit that for design reviews either to the client or testers.

But sometimes what happens is customer feels like this is not exactly what they wanted after the app gets into their hand. But it’s not a problem with the client or with the developer. But it basically doesn’t fit in the App itself.

Then the client shares the feedback and the back and forth continues till the client gets satisfied.

You see the problem now. There’re also other problems such as

• The time between developing and testing increases exponentially⌛
• If the App’s size is big, then often you will end up creating the same widget twice because you won’t know if there’s already a widget that you’ve created or not🌀
• Testing widgets across multiple devices, themes, and settings can be time-consuming and prone to errors⚠️

Now that you know all of the problems, let’s talk about the solution now.💡

2. Introduction to WidgetBook

If I have to define WidgetBook in one sentence then it’s a Flutter package that helps to speed up the development process by cataloging their widgets that you can test on multiple devices and themes.

WidgetBook is built to solve all the problems which I described earlier.

With WidgetBook, you can catalog all components of your App. It enables developers to test widgets across different devices, themes, locales, text scales and more, thus ensuring adaptability and responsiveness.

Now that you know what problems WidgetBook is aimed to solve, let’s get into the programming part 👨‍💻

3. Setting up WidgetBook

I’ll be using the new beta release of the WidgetBook since I found it stable throughout my testing 🧪

You can set up a WidgetBook via 2 methods: By doing it Manually and by using Code Generation. In this part, we will look at the manual setup.

Step — 1

• Add the widgetbook dependency as the dev dependency inside your pubspec.yaml file.

Step — 2

• Inside lib , create a file named app.widgetbook.dart
• Your folder structure should look like this:

Step — 3

• Now inside app.widgetbook.dart , add this code.

• Here, we’re creating another runApp() method, which will be used to run our WidgetBook.
• We also have one StatelessWidget called MyApp . Inside it, we’ve Widgetbook.material() that indicates that we’ll be using material theme inside our WidgetBook.

Step — 4

• Now run your app on either macOS or on Windows
• If you’re using macOS then ou can use this command in the terminal:

flutter run -d macos -t lib/app.widgetbook.dart

• Then you’ll see a window like this:

Now that you’ve learned how to set up the WidgetBook. Let’s see how you can structure your widgets in WidgetBook. But before that, let’s learn one important concept.😉

4. Components and UseCases

• Suppose you have to integrate 3 types of buttons in your App. OutlinedButton, ElevetedButton and a TextButton
• Thus, You can say that all the 3 types of buttons are variants of a Button component. And the types of the button are called the UseCases in Widgetbook.
• Now that you know the meaning of Component and UseCases, let’s see how you can add it inside the WidgetBook.

Adding Components and UseCases inside WidgetBook

• First of all, consider this snippet:

• Inside the build method of this widget, we’re returning Widgetbook.material which takes 2 parameters: addons and directories .
• Now, inside the directories folder, you can add your Component and UseCases like this:

‍

• Now let’s talk about the parameters of these widgets.
• WidgetbookComponent : This widget takes 2 arguments: The name of the Component and the list of the UseCases.
• WidgetbookUseCase : This widget also takes 2 arguments: The name of the UseCase and the widget for the UseCase which is getting returned via builder parameter.
• If you run the app now, you should see something like this:

5. WidgetbookCategory and WidgetbookFolder

Now that you know how you can add components and use cases inside your WidgetBook. What will happen when you want to organize different kinds of components inside WidgetBook?

WidgetBook has covered that one for you too😉 Let’s see how can you organize components inside a folder like this:

Consider the below snippet:

‍

• If you look into this code, inside the directories parameter, we’ve one widget called WidgetbookCategory that takes the name of the category and the list of the components.
• WidgetBook provides 2 widgets that you can use to structure your Components and UseCases. WidgetbookCategory and WidgetbookFolder
• If you want to add subfolders or categories inside these 2 widgets, then you can easily add another WidgetbookCategory or WidgetbookFolder inside them. But WidgetbookComponent can only contain WidgetbookUseCases

6. Knobs

This one is by far the most liked feature of mine in WidgetBook🤩 Knobs allows developers to change widget’s parameters in real-time. Changing the parameters helps developers and designers to better understand the functionality of a component.

But what do I mean by changing parameters in run-time? For that, let’s look at the demo first:

Now, consider this widget:

‍

It’s a basic widget that accepts title from the constructor and shows inside the AppBar. Nothing fancy, right?🤔

Now let’s see how can we change the title in the run-time inside WidgetBook. For that, consider this snippet:

‍

‍

• In this use case, we are returning the HomePage widget. But inside the title property, we’re using context.knobs.text in which we’re passing the label and the initialValue property. Let’s discuss about them.
• lable : The title of the property
• initialValue : The initial value for the widget

WidgetBook provider different types of knobs like:

I have created a GitHub repo of the demo of WidgetBook in which you can check out different types of use cases of knobs and add-ons which we will talk about now.

7. Add-ons

Till now, we were exploring the directories inside Widgetbook.material, but there’s also one other property called addons which we kept empty from the beginning. It’s time to explore them now😉

In the beginning, we talked about changing themes and text scale factors in real-time inside WidgetBook. This is achievable through add-ons. WidgetBook comes with a bunch of add-ons that you can use. Let’s discuss them one by one.

1. Theme Add-on

The theme Add-on provides theming for previewing your use cases in WidgetBook. Thus, you can check and verify your themes in real time.

• WidgetBook provides 3 types of theme add-ons: MaterialThemeAddon , CupertinoThemeAddon and a CustomThemeAddon
• Let’s see the example of MaterialThemeAddon :

• Inside MaterialThemeAddon , we’re passing the settings parameter as MaterialThemeSetting.firstAsSelected which comes from the WidgetBook. It means that it will select the first theme when you load WdigetBook for the first time.
• Inside MaterialThemeSetting.firstAsSelected , we are passing a list of WidgetBookTheme in which we’re returning the default theme. But if you want to add your own ThemeData class then you can add that to the inside data property.

2. Text Scale Add-on

As the name suggests, this Add-on allows you to change the text scale for previewing your use cases. By adding this, you can check if your layout is going to break or not when the scale of the text changes.

Let’s see the code for it:

• Here, We’re passing TextScaleAddon inside the addons property of Widgetbook.material.
• Inside the TextScaleAddon , we’re passing different scale settings for the app.

3. Frame Add-on

As you can see in this GIF, this add-on provides you the ability to view and test all of your use cases on different scree-sizes along with the frames of those devices.

WidgetBook gives you a bunch of Android, iOS and Desktop devices that you can use directly. You can also create your own custom device if you want.

You can use this add-on like this:

‍

‍

• Here we’ve got a few new characters to talk about:
• DefaultDeviceFrame : With this class, you can see the device outlines in WidgetBook.
• NoFrame : As the name suggests, it’s a device-less frame that will be resized whenever the Widgetbook window is changed.
• WidgetbookFrame : This won’t show any device outlines while still keeping the resolution of the device you select.

You can also define your own devices by extending the Device like this:

If you want to try this on your own then you can check out my GitHub repository:

‍

https://github.com/Cavin6080/Widgetbook-demo

‍

I hope you learned something new from this blog. If you didn’t understand any of this part or have any doubts, then you can ask me in the comments, or on my LinkedIn and Twitter.

In the next part, we’ll learn how can we automate the whole process of defining use cases and other things by leveraging code generation😉

‍

‍