Progress
A determinate progress indicator, linear or circular, with an auto-generated percentage label or status icon.
Overview
Progress renders a determinate progress bar — linear or circular — driven by a value/max pair. It auto-generates a percentage label (or, once a status is set, swaps the label for a success/error icon), and exposes slots/slotProps for full control over the label, icon, track, and indicator.
Import
import { Progress } from '@unflowio/ui/components/Progress';Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | Required. Current value, relative to max |
label | string | — | Accessible name for the progressbar, e.g. "Storage used". Required unless aria-label or aria-labelledby is passed |
max | number | 100 | Upper bound value is measured against |
type | 'linear' | 'circular' | 'linear' | Renders a circular indicator instead of the default linear bar |
status | 'success' | 'error' | — | Tints the indicator and swaps the label for a status icon |
hideLabel | boolean | — | Hides the auto-generated label/icon |
size | 'xs' | 'sm' | 'md' | number | 'sm' | Preset size token, or a custom size in px. Controls the diameter when type is circular, and the bar height when type is linear |
thickness | number | size preset's thickness | Stroke width in px. Only used when type is circular |
roundedIndicator | boolean | true | Rounds the indicator's stroke ends. Only used when type is circular |
capPercentage | number | — | Restricts the track and indicator to a gauge-style arc spanning this percentage (0-100) of the full circle, leaving a gap centered at the bottom so the ring never fully closes. Only used when type is circular |
Basic usage
<Progress value={65} label="Storage used" />Circular
Set type="circular" to render a ring instead of a bar. size controls the diameter and accepts the same preset tokens (xs/sm/md) or a custom pixel value.
<Progress type="circular" value={65} size="md" label="Storage used" />Status
Setting status tints the indicator and swaps the percentage label for a status icon, on both linear and circular variants.
<Progress value={100} status="success" label="Upload complete" />
<Progress value={75} status="error" label="Upload failed" />
<Progress type="circular" value={100} status="success" size="md" label="Upload complete" />
<Progress type="circular" value={75} status="error" size="md" label="Upload failed" />Capped gauge
capPercentage restricts a circular indicator to a gauge-style arc, leaving a gap at the bottom so the ring never fully closes — even once value reaches max.
<Progress type="circular" value={75} size="md" capPercentage={80} label="Seats used" />Customization (slots & slotProps)
| Slot | Type | Description |
|---|---|---|
label | (percentage: number, status: ProgressStatus | undefined) => ReactNode | Overrides the auto-generated percentage label |
icon | (status: ProgressStatus) => ReactNode | Overrides the auto-generated status icon shown once status is set |
| Slot Prop | Props | Description |
|---|---|---|
track | BaseHTMLProps<HTMLDivElement> | The background track element |
indicator | BaseHTMLProps<HTMLDivElement> | The filled indicator element |
label | BaseHTMLProps<HTMLParagraphElement> | The label element |
Accessibility
- The track (or the circular
<svg>) carriesrole="progressbar"witharia-valuenow,aria-valuemin={0},aria-valuemax(mirroringmax) andaria-valuetext(the rounded percentage). - Every progressbar needs a name.
label,aria-labelandaria-labelledbyall land on the progressbar element, not the container; a console warning fires in development when none is set. - The default percentage label is
aria-hidden, because it repeatsaria-valuetext. A customslots.labelor a status label stays exposed. Hiding the label viahideLabeldoesn't remove any accessible information.