widgetbook/widgetbookLight logoWidgetbook

List Knob

The list knob renders a dropdown field in the Widgetbook UI where you can dynamically change the value for a widget property. This is particularly useful for properties that require a dynamic input with different states or objects of a specific type, such as status enums.

Varients

The list knob has two variants:

  • context.knobs.list(): This variant allows you to enter a value of dynamic type. It does not accept null values.
  • context.knobs.listOrNull(): This variant allows you to enter a value of dynamic type or null. It is useful when the property can be optional.

Properties

In addition to the knob's base properties, the list knob includes the following:

optionsTrequired

The options shown in the dropdown. The type of the options must be the same as the type of the property.

labelBuilderLabelBuilder<T>optional

A function to format the options for display in the dropdown.

context.knobs.list()

Example

Usage

To use a list knob, call the context.knobs.list() method.

Example: List Knob
@UseCase(type: MyWidget, name: 'Default')
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    status: context.knobs.list( 
      label: 'status', 
      options: [ 
        OnlineStatusType.online, 
        OnlineStatusType.offline, 
        OnlineStatusType.busy, 
      ], 
      labelBuilder: (value) => value!.name, 
    ), 
  );
}

enum OnlineStatusType { online, offline, busy }

context.knobs.stringOrNull()

Example

Usage

To use the nullable list knob, call the context.knobs.listOrNull() method.

Example: Nullable List Knob
@UseCase(type: MyWidget, name: 'Default')
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    status: context.knobs.listOrNull( 
      label: 'status', 
      options: [ 
        OnlineStatusType.online, 
        OnlineStatusType.offline, 
        OnlineStatusType.busy, 
      ], 
      labelBuilder: (value) => value!.name, 
    ), 
  );
}

enum OnlineStatusType { online, offline, busy }

Multi-snapshot Support

Multi-snapshot support allows you to generate multiple screenshots of a single use case with varying values using KnobsConfigs and AddonsConfigs.

Regular list knob

Example: ListKnobConfig
@UseCase(
  type: MyWidget,
  name: 'Default',
  cloudKnobsConfigs: { 
    'online': [ListKnobConfig('status', 'online')], 
    'offline': [ListKnobConfig('status', 'offline')], 
    'busy': [ListKnobConfig('status', 'busy')], 
  }, 
)
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    status: context.knobs.list(
      label: 'status',
      options: [
        OnlineStatusType.online,
        OnlineStatusType.offline,
        OnlineStatusType.busy,
      ],
      labelBuilder: (value) => value.name,
    ),
  );
}

enum OnlineStatusType { online, offline, busy }

Nullable String Knob

Example: NullKnobConfig
@UseCase(
  type: MyWidget,
  name: 'Default',
  cloudKnobsConfigs: { 
    'no status': [NullKnobConfig('status')], 
    'online': [ListKnobConfig('status', 'online')], 
  }, 
)
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    status: context.knobs.listOrNull(
      label: 'status',
      options: [
        OnlineStatusType.online,
        OnlineStatusType.offline,
        OnlineStatusType.busy,
      ],
      labelBuilder: (value) => value!.name,
    ),
  );
}

enum OnlineStatusType { online, offline, busy }
Edit this page on GitHub
Slider
String