# Duration Arg

The Duration arg renders a set of input 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, seconds, and milliseconds.

## Variants

The Duration arg has two variants:
- `DurationArg`: Allows you to enter a `Duration` value. Does not accept `null` values.
- `NullableDurationArg`: Allows you to enter a `Duration` value or set it to `null`. Useful when the property is optional.

## Properties

Besides the [base properties](/args/overview), the Duration arg supports one additional property to control which time units are displayed:

| Property | Type | Default | Description |
|---|---|---|---|
| `units` | `Set<DurationUnit>` | `{DurationUnit.hours, DurationUnit.minutes, DurationUnit.seconds, DurationUnit.milliseconds}` | 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`).

## `DurationArg`

### Example

<iframe
  src="https://preview.next.widgetbook.io/#/?path=args/duration/DurationText/duration&panels=args"
  width="100%"
  height="240px"
/>

### Usage

```dart title="my_widget.stories.dart"
final $Default = _Story(
  args: _Args(
    duration: DurationArg(const Duration(seconds: 5)), // [!code highlight]
  ),
);
```

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

```dart title="Example: DurationArg with custom units"
final $Default = _Story(
  args: _Args(
    duration: DurationArg( // [!code highlight]
      const Duration(seconds: 5), // [!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]
  ),
);
```

## `NullableDurationArg`

### Example

<iframe
  src="https://preview.next.widgetbook.io/#/?path=args/duration/DurationText/durationOrNull&panels=args"
  width="100%"
  height="240px"
/>

### Usage

```dart title="my_widget.stories.dart"
final $Default = _Story(
  args: _Args(
    duration: NullableDurationArg(null), // [!code highlight]
  ),
);
```