Widgetbook 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.material(
      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:

WidgetbookFrameCommentIs default
WidgetbookFrame.defaultFrameThe default frame of Widgetbook
WidgetbookFrame.noFrameThis just shows the use case without any device restrictions
WidgetbookFrame.deviceFrameA frame known from the device_frame package

If the WidgetbookFrame.deviceFrame 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 custom frame or an existing implementation of a device frame.

For the device_frame package the builder looks like this:

Widgetbook.material(
  deviceFrameBuilder: (context, device, renderMode, child) {
    if (renderMode == DeviceFrame.deviceFrame()) {
      return frame.DeviceFrame(
        device: device,
        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,
    );
  },
)

appBuilder

The appBuilder allows developer to inject an app-construct like MaterialApp, CupertinoApp or WidgetsApp into the Widget tree. The default implementations for the appBuilder are defined here.

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.