# Duration Knob

The Duration knob renders a set of text fields in the Widgetbook UI where you can dynamically enter a `Duration` value for a widget property. By default, it shows inputs for hours, minutes, and seconds.

## Variants

The Duration knob has two variants:
- `context.knobs.duration()`: Lets you enter a `Duration` value. It does not accept `null`.
- `context.knobs.durationOrNull()`: Lets you enter a `Duration` value or `null`. This is useful when the property is optional.

## Properties

Besides the knob's [base properties](/knobs/overview#properties), the Duration knob supports one additional property to control which time units are displayed:

| Property | Type | Default | Description |
|---|---|---|---|
| `units` | `Set<DurationUnit>` | `{DurationUnit.hours, DurationUnit.minutes, DurationUnit.seconds}` | The time units to show as separate inputs. |

`DurationUnit` has `days`, `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds`. Units render largest to smallest regardless of set order, and the largest absorbs any overflow so no value is hidden (e.g. with only `seconds`, `Duration(seconds: 90)` shows `90`).

## `context.knobs.duration()`

### Example

<iframe 
  src="https://preview.widgetbook.io/#/?path=knobpreview/duration-knob&panels=knobs" 
  width="100%"
  height="240px"
/>

### Usage

To use a Duration knob, call the `context.knobs.duration()` method.

```dart title="Example: Duration Knob"
@UseCase(type: MyWidget, name: 'Default')
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    duration: context.knobs.duration(label: 'duration') // [!code highlight]
  );
}
```

To customize which time units are shown, pass a `units` set:

```dart title="Example: Duration Knob with custom units"
@UseCase(type: MyWidget, name: 'Default')
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    duration: context.knobs.duration( // [!code highlight]
      label: 'duration', // [!code highlight]
      units: const { // [!code highlight]
        DurationUnit.days, // [!code highlight]
        DurationUnit.hours, // [!code highlight]
        DurationUnit.minutes, // [!code highlight]
        DurationUnit.seconds, // [!code highlight]
        DurationUnit.milliseconds, // [!code highlight]
        DurationUnit.microseconds, // [!code highlight]
      }, // [!code highlight]
    ), // [!code highlight]
  );
}
```

## `context.knobs.durationOrNull()`

### Example

<iframe 
  src="https://preview.widgetbook.io/#/?path=knobpreview/duration-nullable-knob&panels=knobs" 
  width="100%"
  height="240px"
/>

### Usage

To use the nullable Duration knob, call the `context.knobs.durationOrNull()` method.

```dart title="Example: Nullable Duration Knob"
@UseCase(type: MyWidget, name: 'Default')
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    duration: context.knobs.durationOrNull(label: 'duration'), // [!code highlight]
  );
}
```

## Multi-snapshot Support

Multi-snapshot support allows you to generate multiple screenshots of a single use case with varying values using [KnobsConfigs](/cloud/snapshots/multi-snapshot#multi-snapshot-for-knobs) and [AddonsConfigs](/cloud/snapshots/multi-snapshot#multi-snapshot-for-addons).

### Regular Duration Knob

```dart title="Example: DurationKnobConfig"
@UseCase(
  type: MyWidget,
  name: 'Default',
  cloudKnobsConfigs: { // [!code highlight]
    'duration': [DurationKnobConfig('duration', 2000)], // [!code highlight]
  }, // [!code highlight]
)
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    duration: context.knobs.duration(label: 'duration')
  );
}
```

### Nullable Duration Knob

```dart title="Example: NullKnobConfig"
@UseCase(
  type: MyWidget,
  name: 'Default',
  cloudKnobsConfigs: { // [!code highlight]
    'Without duration': [NullKnobConfig('duration')], // [!code highlight]
    'With duration': [DurationKnobConfig('duration', 2000)], // [!code highlight]
  }, // [!code highlight]
)
Widget buildUseCase(BuildContext context) {
  return MyWidget(
    duration: context.knobs.durationOrNull(label: 'duration')
  );
}
```