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 and flutterbook.

Widgetbook Screenshot

See it in action!

Check out the Widgetbook with the example app on our github page. 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

Getting Started

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

Setting up

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 the 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
+ stories
+--- main.dart
+--- widgetbook.dart

The stories/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 stories/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 ✅
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 stories/main.dart.

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

Inject your widgets

Your widgets can be organized into different areas of interest by using Category, Folder, WidgetElement and Story.

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

  @override
  Widget build(BuildContext context) {
    return Widgetbook(
      categories: [
        Category(
          name: 'widgets',
          widgets: [
            WidgetElement(
              name: '$CustomWidget',
              stories: [
                Story(
                  name: 'Default',
                  builder: (context) => CustomWidget(),
                ),
              ],
            ),
          ],
          folders: [
            Folder(
              name: 'Texts',
              widgets: [
                WidgetElement(
                  name: 'Normal Text',
                  stories: [
                    Story(
                      name: 'Default',
                      builder: (context) => Text(
                        'The brown fox ...',
                      ),
                    ),
                  ],
                ),
              ],
            ),
          ],
        ),
      ],
      appInfo: AppInfo(
        name: 'Widgetbook Example',
      ),
    );
  }
}

Set storybook name

Customize Widgetbook's name according to the project by using appInfo:

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

Adding Themes

Import your app's theme for a realistic preview by using Widgetbook's lightTheme and darkTheme properties:

Widgetbook(
  lightTheme: lightTheme,
  darkTheme: darkTheme,
)

Add devices

Customize the preview by defining preview devices:

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

Right now there is a predefinied short list of devices but let us know which you need in our Discord. We will extend the list of predefinied devices in the future!

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,
),

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 or book a call with the founders via Calendly. We're looking forward to build a community and discuss your feedback on our channel! 💙

Libraries

widgetbook