widgetbook 1.0.1-beta.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 and flutterbook.

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

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 WidgetbookCategory, WidgetbookFolder, WidgetbookWidget and WidgetbookUseCase.

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

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

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

A preview in Widgetbook's light or dark mode is only shown when the appropriate theme is set.

If you are in development and haven't defined a theme yet, you can use ThemeData.light() or ThemeData.dark() to use a default theme.

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