Prepared Docs

Progress from @prepared911/ui-core wraps Radix Progress with an optional label and percentage. The primitive exposes the progressbar role and ARIA value attributes; your job is to give the bar a meaningful label, stabilize percentages, and honor reduced-motion expectations for indeterminate animations.

What the component handles

Progressbar role. Root exposes role="progressbar".
ARIA values. aria-valuenow, aria-valuemin, and aria-valuemax update as the value changes.
Label association. The label prop renders visibly and associates with the bar.

What you must provide

A descriptive label. "Uploading image.jpg · 60%" is better than "Loading". Update the label as the operation moves through phases (preparing → uploading → verifying).
Stable percentages. Don't show showPercentage with a volatile value (re-counting every 100 ms). Round to integers and throttle updates so the screen reader doesn't spam the user.
An indeterminate fallback. When the server can't produce meaningful progress yet, omit value (or set it to undefined) and rely on the indeterminate animation with the label.

Keyboard behavior

Progress is non-interactive; there is no keyboard surface. If a cancel affordance is needed, pair the progress bar with a Button beside it.

Semantics and roles

role="progressbar" on the bar.
aria-valuenow, aria-valuemin, aria-valuemax reflect the state.
When indeterminate, omit aria-valuenow so the rotor announces "indeterminate".

Progress updates are announced by assistive tech as aria-valuenow changes.
When an operation completes, swap the bar for a permanent confirmation (a Snackbar or inline Callout) so the completion message persists after the bar disappears.

Reduced motion

Indeterminate animation should pause or simplify when prefers-reduced-motion: reduce is set.
Duration-based fills should also respect reduced motion—prefer immediate value updates without an animated sweep.

Known caveats

Fake progress. Animating a bar with no underlying signal is misleading. If progress isn't known, use the indeterminate state or a LoadingIndicator.
Sub-second operations. If the work finishes in under ~300 ms, rendering progress creates flash more than it helps; omit the bar entirely.

Progress / API and Development

Radio / Usage

What the component handles

What you must provide

Keyboard behavior

Semantics and roles

Screen reader announcements

Reduced motion

Known caveats

What the component handles

Progressbar role. Root exposes role="progressbar".
ARIA values. aria-valuenow, aria-valuemin, and aria-valuemax update as the value changes.
Label association. The label prop renders visibly and associates with the bar.

What you must provide

A descriptive label. "Uploading image.jpg · 60%" is better than "Loading". Update the label as the operation moves through phases (preparing → uploading → verifying).
Stable percentages. Don't show showPercentage with a volatile value (re-counting every 100 ms). Round to integers and throttle updates so the screen reader doesn't spam the user.
An indeterminate fallback. When the server can't produce meaningful progress yet, omit value (or set it to undefined) and rely on the indeterminate animation with the label.

Keyboard behavior

Progress is non-interactive; there is no keyboard surface. If a cancel affordance is needed, pair the progress bar with a Button beside it.

Semantics and roles

role="progressbar" on the bar.
aria-valuenow, aria-valuemin, aria-valuemax reflect the state.
When indeterminate, omit aria-valuenow so the rotor announces "indeterminate".

Progress updates are announced by assistive tech as aria-valuenow changes.
When an operation completes, swap the bar for a permanent confirmation (a Snackbar or inline Callout) so the completion message persists after the bar disappears.

Reduced motion

Indeterminate animation should pause or simplify when prefers-reduced-motion: reduce is set.
Duration-based fills should also respect reduced motion—prefer immediate value updates without an animated sweep.

Known caveats

Fake progress. Animating a bar with no underlying signal is misleading. If progress isn't known, use the indeterminate state or a LoadingIndicator.
Sub-second operations. If the work finishes in under ~300 ms, rendering progress creates flash more than it helps; omit the bar entirely.

Progress / API and Development

Radio / Usage

What the component handles

What you must provide

Keyboard behavior

Semantics and roles

Screen reader announcements

Reduced motion

Known caveats