Quick Start


The first step to start using Widgetbook is to create a new separate Flutter app for your widget catalog.

  1. Create a new Flutter project inside your app's directory:

    ## All platforms
    flutter create widgetbook --empty
    ## Certain platforms
    flutter create widgetbook --empty --platforms=web,macos
  2. To avoid naming conflict with the Widgetbook pub package, change the project name to widgetbook_workspace inside the widgetbook/pubspec.yaml file:

    - name: widgetbook
    + name: widgetbook_workspace
  3. Add the following dependencies to your widgetbook project:

    flutter pub add widgetbook widgetbook_annotation dev:widgetbook_generator dev:build_runner
  4. Add your app as a path dependency to the widgetbook/pubspec.yaml file:

        path: ../

After finishing the setup, the folder structure should look something like this:

├── pubsepc.yaml
├── lib/
├── ...
└── widgetbook/
    ├── pubsepc.yaml
    ├── lib/
    └── ...

And the widgetbook/pubspec.yaml file should look like this:

name: widgetbook_workspace
# ...

  widgetbook_annotation: ^3.1.0
  widgetbook: ^3.8.0
    path: ../

  widgetbook_generator: ^3.8.0

Your First Use-case#

In this section, you will create a simple use-case and show it inside your Widgetbook app.

  1. Choose a widget from your_app that you want to catalog. For this example, we will use the imaginary CoolButton widget.

  2. Create a file inside your widgetbook app at widgetbook/lib/cool_button.dart

    If your widget needs some parameters, you can pass some constants for now for simplicity. Later you can check how to use Knobs.

    import 'package:flutter/material.dart';
    import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;
    // Import the widget from your app
    import 'package:your_app/cool_button.dart';
    @widgetbook.UseCase(name: 'Default', type: CoolButton)
    Widget buildCoolButtonUseCase(BuildContext context) {
      return CoolButton();
  3. Create a file inside your widgetbook app at lib/main.dart

    import 'package:flutter/material.dart';
    import 'package:widgetbook/widgetbook.dart';
    import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;
    // This file does not exist yet,
    // it will be generated in the next step
    import 'main.directories.g.dart';
    void main() {
      runApp(const WidgetbookApp());
    class WidgetbookApp extends StatelessWidget {
      const WidgetbookApp({super.key});
      Widget build(BuildContext context) {
        return Widgetbook.material(
          // The [directories] variable does not exist yet,
          // it will be generated in the next step
          directories: directories,
  4. Run the following command to generate the main.directories.g.dart file that has the directories variable:

    dart run build_runner build -d
  5. Now you can run your Widgetbook app and see your use-case in action:

    flutter run
  6. Add some Addons to your Widgetbook app to customize the appearance of your use-case.