◇

Progress

2 parts

A bar that shows the completion progress of a task, typically a horizontal fill that grows from empty to full. Use it for file uploads, multi-step form progress, loading indicators, or any operation whose progress you can measure (or, with a null value, signal as indeterminate). The root renders the accessible progressbar (wiring up aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, and an aria-label accessible name) and derives the current state — indeterminate, loading, or complete — which it provides via context and exposes on the data-state attribute. Pair it with ProgressIndicator for the visual fill. Both modelValue and max are two-way (v-model / v-model:max): bad inputs (NaN, negatives, out-of-range, max <= 0) are validated, clamped, and reported in development, so the rendered ARIA is always valid.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  ProgressRoot,
  ProgressIndicator,
} from '@robonen/primitives/display/progress';

<ProgressRoot>
  <ProgressIndicator />
</ProgressRoot>

API Reference

ProgressRoot

Root

A bar that shows the completion progress of a task, typically a horizontal fill that grows from empty to full. Use it for file uploads, multi-step form progress, loading indicators, or any operation whose progress you can measure (or, with a `null` value, signal as indeterminate). The root renders the accessible `progressbar` (wiring up `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`, and an `aria-label` accessible name) and derives the current `state` — `indeterminate`, `loading`, or `complete` — which it provides via context and exposes on the `data-state` attribute. Pair it with `ProgressIndicator` for the visual fill. Both `modelValue` and `max` are two-way (`v-model` / `v-model:max`): bad inputs (`NaN`, negatives, out-of-range, `max <= 0`) are validated, clamped, and reported in development, so the rendered ARIA is always valid.

Prop	Type	Default	Description
`modelValue`?	`number \| null`	—	Current value. `null` denotes an indeterminate progress bar. Two-way via `v-model`.
`max`?	`number`	`100`	Maximum value. Two-way via `v-model:max`.
`getValueLabel`?	`(value: number \| null, max: number) => string \| undefined`	`(v, m) => v == null ? undefined : `${Math.round((v / m) * 100)}%``	Builds the `aria-valuetext` describing the current value in a human-readable form. Receives the resolved value (`null` when indeterminate) and max.
`accessibleLabel`?	`string \| ((value: number \| null, max: number) => string \| undefined)`	—	Accessible name for the progressbar, rendered as `aria-label`. Accepts a static string or a function of the resolved value and max. Provide this (or an external `aria-labelledby`) so screen readers announce a meaningful name.

Emits

Event	Payload
`update:max`	`[value: number]`
`update:modelValue`	`[value: number \| null]`

ProgressIndicator

Indicator

The visual fill of the progress bar, rendered inside `ProgressRoot`. It reads the value, max, and state from context and exposes them via `data-state`, `data-value`, and `data-max` (plus matching slot props) so you can size and style the fill — e.g. translating it by the completion percentage.

No props or events — renders its element and forwards attributes.