Progress

A determinate or indeterminate progress bar.

Last updated

Show code
<Progress value={60} label="Upload progress" />

For a ring or a gauge see Circular progress.

Add

npx @ava-ui/apogee add progress

No Apogee component dependencies, no icons. Zero JS.

Usage

---
import Progress from '@/components/apogee/Progress/Progress.astro'
---
<Progress value={40} max={100} label="Profile completeness" />

API

@composable — exposed to Content Editors in AVA. Any other attribute passes through to the root <div role="progressbar">.

Prop Type Default Description
value number 0 Current value, 0–max. Ignored visually when indeterminate.
min number 0 Lower bound.
max number 100 Maximum value.
label string — Accessible label (aria-label) — there’s no visible text otherwise.
indeterminate boolean false Shows a sliding animated fill instead of a value-based width; drops aria-valuemin / aria-valuemax / aria-valuenow.
size 'small' | 'medium' 'medium' Bar thickness: 4 / 8px.
color 'primary' | 'neutral' | 'critical' | 'positive' | 'warning' 'primary' Hue of the fill.
labelPosition 'none' | 'end' | 'bottom' | 'floating' 'none' Where the value text shows: after the bar, under it, or in a chip that floats above the fill.
format string '{percent}%' Value text template; {value}, {percent} and {max} are replaced.
class string — Extra classes on the root wrapper, merged last.

Value labels

Every labelPosition, with a format:

60%
60 of 100 files
60%
Show code
<Progress value={60} label="Upload" labelPosition="end" />
<Progress value={60} label="Upload" labelPosition="bottom" format="{value} of {max} files" />
<Progress value={60} label="Upload" labelPosition="floating" />

Sizes

Show code
<Progress value={40} size="small" label="Small" />
<Progress value={40} size="medium" label="Medium" />

Colours

Show code
<Progress value={60} color="primary" label="Primary" />
<Progress value={60} color="neutral" label="Neutral" />
<Progress value={60} color="critical" label="Critical" />
<Progress value={60} color="positive" label="Positive" />
<Progress value={60} color="warning" label="Warning" />

States

Determinate, at a few values:

Show code
<Progress value={0} label="0%" />
<Progress value={40} label="40%" />
<Progress value={100} label="100%" />

Indeterminate — a 40%-wide fill slides on a loop:

Show code
<Progress indeterminate label="Loading" />

Examples

A step counter using a non-percentage max:

<Progress value={2} max={4} label="Step 2 of 4" />

Accessibility

  • role="progressbar" with aria-valuemin / aria-valuemax / aria-valuenow; all three are omitted when indeterminate, matching the ARIA spec for an indeterminate progress meter.
  • label sets aria-label — always pass one; the bar has no visible text.
  • The indeterminate slide respects prefers-reduced-motion: its 1.2s loop slows to 3s. The determinate fill’s width transition has no separate reduced-motion guard.

Tokens

Token Used for
--background-neutral-faded Track background
--background-primary Fill
--background-inverted / --on-inverted Floating value chip
--duration-slow Determinate fill transition duration
--ease-standard Transition / animation easing

Do / Don’t

  • Do always pass label — the bar has no visible text of its own.
  • Do use indeterminate only when a percentage genuinely can’t be computed; switch to determinate the moment you can.
  • Don’t write the value into the track yourself; use labelPosition, which keeps the text out of the fill.
  • Don’t animate value faster than users can perceive as real progress rather than decoration.

Content

  • label states what’s progressing (“Uploading…”, “Step 2 of 4”), not the percentage — the number is already conveyed through ARIA.

Related

ProgressIndicatorStep N of M as a row of segments, for onboarding flows, wizards and carousels. Zero JS.
MeterA native meter gauge for a measurement in a known range, like disk usage or a score.
SpinnerA spinning loading indicator. Zero JS.
LoaderTextText with a moving shimmer while something loads, crossfading to a done label when it finishes.