Skip to content
WunderUI

Duration Bar

Pro

One step of a run as a bar, measured against the whole run, with a tick at its estimate and red when it runs over.

Playground

Check the stroke widths
8.3s

Installation

Duration Bar comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • Agent Status for the state of a run and the time it has been in that state
  • Run Timeline for the steps of a run with their status, tools and output
  • Progress for how far a task has got, not how long it took
  • Usage Meter for spend against a budget

Estimate

A planned value draws a tick at the estimate. Past it the bar and time turn red and assistive technology hears by how much, but say a failure in words, because red is visual only.

Check the stroke widths
8.3s

Layout

The bar is 140 px wide and the label takes the rest. In fill mode the bar takes the free width, never less than 64 px, while label and time keep the width of their text.

Check the stroke widths
8.3s

Value

The fill is the value divided by the maximum, kept between 0 and 100 percent. Zero draws no fill, a value past the maximum fills the bar, and the time always shows the real number.

Edit the files
8.3s

Text

The time reads 8.3s under a minute and 2m 14s after. A value label replaces the text on the right visually, a format function changes it everywhere, and a long label is cut with an ellipsis.

Run the tests
3.8s

Delta

The delta slot sits after the time, for a badge such as "+58%" or "On time". On phones the label takes its own line and the bar, the time and the delta share the line under it.

Compare tokens
6.3s+58%

Behavior and motion

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

The figure shows a bar with an estimate that it has not reached. A bar without an estimate has no part 5.

Check the stroke widths
8.3s
  • data-slot="duration-bar"

    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.

  • 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.

  • 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.

  • 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.

  • Optional

    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.

  • 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

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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 is a plain component, so this table lists every prop.

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.

PropTypeDefaultDescription
label requiredReactNode—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.
value requirednumber—How long the step took, in seconds unless you pass . Sets the width of the fill and the time.
max requirednumber—The full width of the bar: the longest step or the whole run, in the same unit as . Pass the same to every row of a list.
plannednumber—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 is past it.
tone"default" | "over"— or . Overrides the tone that follows from . colours the bar and the time red and says nothing more to assistive technology.
formatValue(value) => stringformatSeconds. Formats the time, the estimate and the overrun, in the visible text and in the value text. Default: and .
valueLabelReactNode—Replaces the visible time on the right, for example . Assistive technology still hears the computed value text.
fillbooleanfalse by default: the bar is 140 px wide. lets the bar take the free width, never under 64 px, while the label and the time keep their own width.
deltaReactNode—A slot after the time, for a badge with the difference to the estimate. Not shown when empty.
classNamestring—Extra classes for the row, for example a margin or a width.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("duration-bar")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.