widgetbook 2.2.1 copy "widgetbook: ^2.2.1" to clipboard
widgetbook: ^2.2.1 copied to clipboard

outdated

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

Discord style: very good analysis GitHub Workflow Status GitHub Workflow Status

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.

Widgetbook Screenshot

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 Pub Version
package:widgetbook_annotation Pub Version
package:widgetbook_generator Pub Version

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

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! 💙