# Duration Bar

A step's share of the run as a bar, with a tick at the estimate and red when it runs over.

- Category: AI & Agents
- Page: https://wunderui.com/components/duration-bar
- Tier: Core and Pro

## Install

Duration Bar ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { DurationBar, DurationBarTone } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { DurationBar } from "@wunderui/react"

export function StepTime({ seconds, planned, total }: { seconds: number; planned: number; total: number }) {
  return <DurationBar label="Run the tests" value={seconds} max={total} planned={planned} />
}
```

Expected result: You see the label, a 140 px bar filled to the seconds of the total, a small tick at the estimate and the time, for example 3.8s. When the seconds pass the plan, the bar and time turn red.

## When to use

### Use Duration Bar for

- The time of one step of an agent run, against the whole run or the longest step
- A list of steps whose widths should be compared at a glance
- A step with an estimate, to see that it ran over

### Use something else

- [Agent Status](https://wunderui.com/components/agent-status) for the state of a run and the time it has been in that state
- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of a run with their status, tools and output
- [Progress](https://wunderui.com/components/progress) for how far a task has got, not how long it took
- [Usage Meter](https://wunderui.com/components/usage-meter) for spend against a budget

## Behavior

What the bar does with its numbers, its text, assistive technology and motion.

- **Width:** The fill is value divided by max as a percentage, kept between 0 and 100: a value past max fills the bar, a negative one draws nothing. A max of 0 or less counts as 1.
- **Estimate:** With an estimate set, a value past it turns the bar and time red. You can force either tone yourself, and without an estimate or a tone the bar is never red.
- **Format:** Time reads 8.3s under a minute and 2m 14s after, and a whole number loses its decimal. Rounding comes first, so 59.96 s reads 1m 00s, never 60.0s.
- **Assistive technology:** The track is a meter named by the label, running from 0 to the max, with value text like 12.4s, planned 9.6s, 2.8s over. A custom value label is visual only, and the tick is hidden and takes no focus.
- **Narrow containers:** The bar and time keep their width, so the label gives way first. With the fill option the label still gives way first, and the bar never goes under 64 px.
- **Motion:** When the value changes, the fill grows or shrinks on the ambient duration with the entrance curve, but not on first render. It animates width, so keep it for a few bars, not hundreds.
- **Reduced motion:** With reduced motion the fill jumps to its new width. The time, the tick and the colours say the same without motion.
- **Failure and abort:** The bar has no failed or cancelled state. Show a failed step in the over tone with a label like Failed after 4.1 s, a step that never ran as 0 with Not run, and say it in a status line.

## Anatomy

- `DurationBar`: One row: a label, a bar and the time, 12 px apart. It fills the width of its parent and is marked as default or over.
- `Label`: The step name in 13 px secondary text. It takes the width the bar and time leave over, is cut with an ellipsis when that is not enough, and names the bar for assistive technology.
- `Track`: The bar: 6 px high, fully rounded, 140 px wide (or the free width, never under 64 px). It is a meter with the time and estimate in its value text and takes no focus.
- `Fill`: The value divided by the max as a width, kept between 0 and 100 percent. It is the brand colour, or red when the step is over, and a value of 0 draws no fill.
- `Estimate tick`: A 2 px wide, 10 px high mark at the estimate, drawn only when an estimate is set. It is decorative, since the estimate is also in the value text.
- `Time`: The time: 8.3s under a minute, 2m 14s after, in 12 px tabular figures, at least 40 px wide. It turns red when the step is over, and a custom label can replace it.

## Best practices

### When to use

- Use DurationBar for the time of one step against a max; stack several for the phases of a run. For how far a task has got use Progress, for the state of a run Agent Status.

### Do

- Pass the same max to every row of a list, the whole run or the longest step, so the bars can be compared. A max of 0 or less counts as 1.
- Pass the planned time where an estimate exists. Past it the bar and time turn red, and the text for assistive technology says by how much.
- Say a failure or skipped step in words, in a status line next to the bars. The over tone and a custom label are visual, so assistive technology still hears the number.
- Keep the label short. It gives way first: in a narrow card it is cut with an ellipsis, and at 320 px a long label can shrink to a few letters.
- Show tiny and zero steps as well. A step under 2 percent is a sliver and a value of 0 draws no fill, but the time on the right keeps both readable.

### Don't

- Don't rely on colour. Red reaches only people who see it, so the time, the estimate tick and the sentence next to the list must say the same.
- Don't use it for progress. A bar that fills while work is still to do answers how far, not how long, so use Progress.

## API reference

### DurationBar

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode |  | The name of the step. Shown on the left and used as the name of the meter. Keep it short: it is cut with an ellipsis when the row is narrow. |
| max* | number |  | The full width of the bar: the longest step or the whole run, in the same unit as `value`. Pass the same `max` to every row of a list. |
| value* | number |  | How long the step took, in seconds unless you pass `formatValue`. Sets the width of the fill and the time. |
| className | string |  | Extra classes for the row, for example a margin or a width. |
| delta | React.ReactNode |  | A slot after the time, for a badge with the difference to the estimate. Not shown when empty. |
| fill | boolean | false | `false` by default: the bar is 140 px wide. `true` lets the bar take the free width, never under 64 px, while the label and the time keep their own width. |
| formatValue | (value: number) => string | formatSeconds | `(value: number) => string`. Formats the time, the estimate and the overrun, in the visible text and in the value text. Default: `8.3s` and `2m 14s`. |
| planned | number |  | The estimate, in the same unit. Draws the tick, adds the estimate and the overrun to the value text and turns the bar red when `value` is past it. |
| tone | "default" \| "over" |  | `default` or `over`. Overrides the tone that follows from `planned`. `over` colours the bar and the time red and says nothing more to assistive technology. |
| valueLabel | React.ReactNode |  | Replaces the visible time on the right, for example `6 min actual · planned 4 min`. Assistive technology still hears the computed value text. |

## Examples

### Estimate: none, within, over, a tone you set

### Layout: the fixed bar and the bar that fills

### Value: typical, tiny, zero, past max, minutes

### Text: the time, your own text, your own format, a long label

### Delta: the difference to the estimate

## In context

### Run phases: every step against the whole run

Five steps under each other, each bar measured against the total, so the widths compare the steps. In the failed run the broken step is red, and a status line says how the run went.

### Live step: the bar grows while the step runs

Press Start the step. The bar grows with the time since the step started and turns red past the estimate, and the status line speaks only when the step goes over or ends.

## For AI agents

`get_component("duration-bar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
