widgetbook 2.2.1

A flutter storybook that helps professionals and teams to catalogue their widgets.

A flutter package which helps developers cataloguing their widgets, testing them quickly on multiple devices and themes, and sharing them easily with designers and clients. Inspired by Storybook.js.

See it in action!

Check out the Widgetbook with the example app on our homepage. Furthermore, you can check out the code of the app at github.

Other packages

package:widgetbook can be used with package:widgetbook_annotation and package:widgetbook_generator to make setting up and maintaining Widgetbook easier. Check out the other packages:

Package	Pub
package:widgetbook
package:widgetbook_annotation
package:widgetbook_generator

Usage

import 'package:flutter/material.dart';
import 'package:widgetbook/widgetbook.dart';

void main() {
  runApp(const HotreloadWidgetbook());
}

class HotreloadWidgetbook extends StatelessWidget {
  const HotreloadWidgetbook({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Widgetbook.material(
      categories: [
        WidgetbookCategory(
          name: 'widgets',
          widgets: [
            WidgetbookComponent(
              name: 'Button',
              useCases: [
                WidgetbookUseCase(
                  name: 'elevated',
                  builder: (context) => ElevatedButton(
                    onPressed: () {},
                    child: const Text('Widgetbook'),
                  ),
                ),
              ],
            ),
          ],
        )
      ],
      themes: [
        WidgetbookTheme(
          name: 'Light',
          data: ThemeData.light(),
        ),
        WidgetbookTheme(
          name: 'Dark', 
          data: ThemeData.dark(),
        ),
      ],
      appInfo: AppInfo(name: 'Example'),
    );
  }
}

Getting Started

This package provides a flutter widget called Widgetbook in which custom widgets from your app can be injected.

Setting up

First, add the dependency to your pubspec.yaml file:

# pubspec.yaml
dev_dependencies:
  widgetbook:

Since the Widgetbook is launched as a separate app, it is recommended to create another main method. This enables you to switch between your app and Widgetbook at any time. You can even launch your app and Widgetbook simultaneously.

The folder structure might look like this:

example_app
├─ lib
│  ├─ main.dart
├─ widgetbook
│  ├─ main.dart
│  ├─ widgetbook.dart
├─ pubspec.yaml

The widgetbook/widgetbook.dart file contains the Widgetbook wrapped within a stateless widget that enables hot reloading. The code looks like this:

class HotReload extends StatelessWidget {
  const HotReload({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Widgetbook(...);
  }
}

In the widgetbook/main.dart run the HotReload widget:

void main() {
  runApp(HotReload());
}

Run the Widgetbook

Widgetbook is supported on the following environments.

Environment	Status	Comment
MacOS	✅
Windows	✅
Linux	✅
Web	✅	No hot reload, but hot restart (see Issue 4)
Mobile	➖	Will run, but is not optimized. If you see a usecase for Widgetbook on mobile let us know.

See the Desktop support for Flutter page for setup instructions.

Run the Widgetbook main method by executing flutter run -t widgetbook/main.dart.

NOTE: If you are using package:widgetbook_generator see the documentation on how to run Widgetbook.

Constructors

Widgetbook allows developers to define whatever Theme they have defined for their app. To accompany every theme and the ones defined by Flutter, the following constructors exist:

Theme	Constructor	Defaults to
Custom Theme	Widgetbook<YourTheme>	➖
Material	Widgetbook.material	Widgetbook<ThemeData>
Cupertino	Widgetbook.cupertino	Widgetbook<CupertinoThemeData>

As you can see from the constructor definitions, Widgetbook allows to define your Theme type to accompany any implementation. However, most developers will likely use Widgetbook.material as shown in the example above.

Knobs

Knobs can be used to dynamically change the parameters passed to a usecase.

WidgetbookUseCase(
  name: 'elevated',
  builder: (context) => MyHomePage(
    title: context.knobs.text(
      label: 'Title Label',
      initialValue: 'HomePage',
    ),
  )
)

Available Knobs

Name	Type
boolean	bool
nullableBoolean	bool?
text	String
nullableText	String?
slider	double
nullableSlider	double?
number	num
nullableNumber	num?
options	T

You can see an example of this and different knobs available here.

Properties

Widgetbook defines various properties to customize how your Widgets will be rendered.

categories

Your widgets can be catalogued by using different Organizers. The available organizers are: WidgetbookCategory, WidgetbookFolder, WidgetbookComponent and WidgetbookUseCase.

Both WidgetbookCategory and WidgetbookFolder can contain sub folders and WidgetbookComponent elements. However, WidgetbookComponent can only contain WidgetbookUseCases.

class HotReload extends StatelessWidget {
  const HotReload({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Widgetbook(
      categories: [
        WidgetbookCategory(
          name: 'widgets',
          widgets: [
            WidgetbookComponent(
              name: '$CustomWidget',
              useCases: [
                WidgetbookUseCase(
                  name: 'Default',
                  builder: (context) => CustomWidget(),
                ),
              ],
            ),
          ],
          folders: [
            WidgetbookFolder(
              name: 'Texts',
              widgets: [
                WidgetbookComponent(
                  name: 'Normal Text',
                  useCases: [
                    WidgetbookUseCase(
                      name: 'Default',
                      builder: (context) => Text(
                        'The brown fox ...',
                      ),
                    ),
                  ],
                ),
              ],
            ),
          ],
        ),
      ],
      appInfo: AppInfo(
        name: 'Widgetbook Example',
      ),
    );
  }
}

appInfo

The appInfo property allows users to label the Widgetbook in case you are maintaining more than one Widgetbook for multiple projects. Customize Widgetbook's name according to the project by using appInfo:

Widgetbook.material(
  appInfo: AppInfo(
    name: 'Your apps name',
  ),
)

Localization

Widgetbook defines the two properties supportedLocales and localizationsDelegates to support localization of Widgets. These values behave as described in Flutter Internationalization.

Widgetbook.material(
  localizationsDelegates: [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: [
    Locale('en'), // English, no country code
    Locale('es'), // Spanish, no country code
  ],
)

themes

Import your app's theme for a realistic preview by using Widgetbook's theme property:

Widgetbook.material(
   themes: [
    WidgetbookTheme(
      name: 'Light',
      data: ThemeData.light(),
    ),
    WidgetbookTheme(
      name: 'Dark',
      data: ThemeData.dark(),
    ),
  ],
)

devices

Customize the preview by defining preview devices:

Widgetbook.material(
  devices: [
    Apple.iPhone11,
    Samsung.s21ultra,
  ]
)

Right now, there is a predefined list of devices. If you need more devices, you can either add them on your own or let us know which ones you need in our Discord.

Define your own device

You can also define your own device by using the Device class:

Device(
  name: 'Custom Device',
  resolution: Resolution.dimensions(
    width: 500,
    height: 500,
    scaleFactor: 2,
  ),
  type: DeviceType.tablet,
),

frames

The frames property allows developers to define different ways of how the frame of a device is visualized. The following WidgetbookFrames are defined:

WidgetbookFrame	Comment	Is default
WidgetbookFrame.defaultFrame	The default frame of Widgetbook	✅
WidgetbookFrame.noFrame	No frame - this just shows the use case without any device restrictions	✅
WidgetbookFrame.deviceFrame	A frame known from the device_frame package	✅

If the Device Frame option is active, the Widgetbook devices will be mapped to the devices of device_frame.

textScaleFactors

The textScaleFactors property allows you to define a list of different text scales which are injected (and can then be accessed) via the MediaQuery. The list defaults to textScaleFactors of [ 1.0 ].

Builders

Widgetbook exposes various builder functions to allow customization of how WidgetbookUseCases are displayed.

deviceFrameBuilder

The deviceFrameBuilder in combination with the frames property can be used to add your or an existing implementation of a device frame:

For the device_frame package this can look like this:

Widgetbook.material(
  deviceFrameBuilder: (context, device, renderMode, child) {
    if (renderMode == DeviceFrame.deviceFrame()) {
      return frame.DeviceFrame(
        device: frame.Devices.ios.iPhone12,
        screen: child,
      );
    }

    // default to no device frame
    return child;
  },
)

localizationBuilder

The default of localizationBuilder is defined as:

(
  BuildContext context,
  List<Locale> supportedLocales,
  List<LocalizationsDelegate<dynamic>>? localizationsDelegates,
  Locale activeLocale,
  Widget child,
) {
  if (localizationsDelegates != null) {
    return Localizations(
      locale: activeLocale,
      delegates: localizationsDelegates,
      child: child,
    );
  }

  return child;
};

themeBuilder

The themeBuilder allows you to inject theme data into the Widget tree. An implementation for CupertinoThemeData could look like this:

Widgetbook<CupertinoThemeData>(
  themeBuilder: (
    BuildContext context,
    CupertinoThemeData theme,
    Widget child,
  ) {
    return CupertinoTheme(
      data: theme,
      child: child,
    );
  },
)

scaffoldBuilder and useCaseBuilder

Both the scaffoldBuilder and useCaseBuilder can be used to wrap the Widget with e.g. a Scaffold or some other Widget like a Center, Container or Padding.

Supported Flutter version

We are currently aiming to support the latest flutter version.

Using Widgetbook for a package

A lot of app projects implement dedicated packages for UI components. These packages often do not define a (desktop) app. Therefore, it's hard to use Widgetbook for these packages. This section will explain how you can get Widgetbook running in such a scenario.

Let's assume you have set up a monorepo with the following folder structure with two packages ui_components and core_api:

monorepo
├─ docs
├─ packages
│  ├─ ui_components
│  ├─ core_api

To create a widgetbook for the ui_components package, we recommend to create a new folder named widgetbooks in the root of the repository and add a flutter (desktop) app named ui_components_widgetbook. The folder structure of your repository will look like this:

monorepo
├─ docs
├─ packages
│  ├─ ui_components
│  ├─ core_api
├─ widgetbooks
│  ├─ ui_components_widgetbook
│  │  ├─ lib
│  │  ├─ macos
│  │  ├─ pubspec.yaml

Make sure to modify widgetbooks/ui_components_widgetbook/pubspec.yaml to depend on ui_components:

pubspec.yaml:

dependencies:
  ui_components:
    path: ../../packages/ui_components

You can now use all exported Widgets from your library to compose your Widgetbook.

Known Issues

• Hot reloading on web is currently not working properly. This is due to the fact that hot reloading is actually a restart. The problem is tracked in widgetbook/issues/4. For now we recommended to use MacOS or Windows as a platform for development.

Let us know how you feel about Widgetbook

We are funded and aim to shape Widgetbook to your (and your team's) needs. If you have questions, feature requests or issues let us know on Discord or GitHub. We're looking forward to build a community and discuss your feedback on our channel! 💙