Args

Args is a type-safe way to define and manage the properties of your widgets in Widgetbook. By using Args, you can create interactive stories that allow you to tweak widget properties in real-time, making it easier to visualize different states and configurations.

Args are generated based on your widget's constructor parameters, ensuring type safety and consistency. You can define Args for various data types, including primitives, enums, and complex objects.

import 'package:widgetbook/widgetbook.dart';
import 'package:my_app/my_widget.dart';

part 'my_widget.stories.g.dart';

const meta = Meta(MyWidget.new);

Run the following command to generate the _Args class for your widget:

dart run build_runner build

Now you can create a story with interactive args using the generated _Args class:

final $Active = _Story(
  args: _Args(
    title: StringArg('Hello, Widgetbook!'),
    isEnabled: BoolArg(true),
    count: IntArg(5),
    status: Arg.fixed(MyStatus.active), // Constant value, won't be changeable in the UI
  ),
);

When an arg changes, Widgetbook rebuilds the story with a new key by default. This behavior is especially useful for StatefulWidgets because local state is reset to match the latest arg values.

• StatelessWidget: updates reflect immediately through the new args.
• StatefulWidget: local state is reset on arg change so the widget reflects the updated args.

This means you usually do not need a manual KeyedSubtree in your story.

If you need to preserve local state across arg updates, override setup and return the widget unchanged:

final $Default = _Story(
  setup: (context, widget, args) => widget,
  args: _Args(
    initialValue: IntArg(10),
  ),
);

Use this only when keeping local state is intentional.

You can programmatically update an arg's value from within a story using arg.update(context, newValue). This syncs the new value with the arg panel UI and URL query parameters, creating a two-way binding between widget interactions and arg controls.

A common use case is keeping the arg panel in sync when a user interacts with the widget itself, for example pressing a button that changes state.

Callback parameters (like onChanged, onPressed) need access to BuildContext to update args. Use BuilderArg for this. It takes a builder function that receives the context and returns the callback value:

final $Default = _Story(
  args: _Args(
    onChanged: BuilderArg(
      (context) => (value) {
        final args = WidgetbookState.of(context).story!.args as _Args;
        args.initialValueArg.update(context, value);
      },
    ),
  ),
);

In this example, when the user taps the increment/decrement buttons in the Counter widget:

1. The widget calls onChanged with the new count.
2. The callback accesses the story's args via WidgetbookState.
3. args.initialValueArg.update(context, value) updates the initialValue arg panel to reflect the new value.

The result is that the arg panel stays in sync with widget interactions without any manual wiring.

The default source for args generation is the widget's constructor. However, you can customize this behavior by providing a custom args class via Meta.argsType as follows:

import 'package:widgetbook/widgetbook.dart';
import 'package:my_app/my_widget.dart';

part 'my_widget.stories.g.dart';

const meta = Meta(MyWidget.new, argsType: MyArgs.new);

class MyArgs {
  MyArgs({
    required this.number,
  });

  final int number;
}

After running the build runner, a custom _Args class will be generated based on your MyArgs class. However, you will need to manually map the args in your story using the builder parameter:

final $Custom = _Story(
  args: _Args(
    number: IntArg(10),
  ),
  builder: (context, args) {
    return MyWidget(
      title: 'Custom Title',
      isEnabled: true,
      count: args.number,
      status: MyStatus.inactive,
    );
  },
);

Widgetbook offers first-class support for all primitive and common data types through various Arg classes:

In cases where you want to use a constant value that shouldn't be changeable in the Widgetbook UI, you can use the Arg.fixed<T> constructor. This is useful for parameters that are not relevant for interactive tweaking.

final $FixedExample = _Story(
  args: _Args(
    title: Arg.fixed('Fixed Title'),
    isEnabled: Arg.fixed(false),
    count: Arg.fixed(42),
  ),
);

If all the args are fixed, you can use the _Args.fixed constructor for brevity:

final $AllFixed = _Story(
  args: _Args.fixed(
    title: 'Fixed Title',
    isEnabled: false,
    count: 42,
  ),
);

If you are wondering what type of arg will be generated based on your constructor parameter, here is a mapping. primitive.default refers to the type's natural default (e.g., false for bool, 0 for int), while param.default refers to the default value specified in the constructor.