Progress
Progress communicates the completion status of one task that takes time.
Overview and decision boundary
Use Progress to communicate the completion status of one task that takes time.
Invent values to make an operation appear active.
Uploading files68%
Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add progressimport { Progress } from '@nerio-ui/ui';Usage
import { Progress } from '@nerio-ui/ui';<Progress label="Uploading files" value={68} valueLabel="68%" />Variants
| Contract | Description |
|---|---|
No visual variants | Progress intentionally has no size, tone, status, striped, or decorative variants. |
Anatomy
| Slot | Description |
|---|---|
root | Semantic progressbar root with the accessible name and normalized range values. |
header | Optional row for visible label and value text. |
label | Optional visible task name associated through aria-labelledby. |
value | Optional visible completion text from valueLabel. |
track | Visual-only neutral completion track. |
indicator | Visual-only transform-scaled fill or indeterminate segment. |
States
| State | Behavior |
|---|---|
indeterminate | No finite value is available. aria-valuenow is omitted. |
progressing | A finite normalized value is below max. |
complete | The clamped value reaches max. The indicator does not change to an outcome color. |
Motion
- Determinate updates scale the indicator with transform instead of animating layout size.
- Indeterminate motion uses tokenized duration, easing, and segment width; RTL reverses its direction.
- Reduced motion disables transitions and animation while retaining a static partial segment.
Accessibility
- Progress requires exactly one accessible name: a visible label, aria-label, or aria-labelledby.
- Determinate progress exposes normalized aria-valuemin, aria-valuemax, and the clamped aria-valuenow; indeterminate progress omits aria-valuenow.
- Use valueText for localized non-percentage completion text. Progress is read-only and does not need keyboard focus.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Type | Description |
|---|---|---|
value | number | null | Finite completion value. Defaults to null for indeterminate progress. |
min | number | Range minimum. Defaults to 0; invalid runtime ranges normalize to 0–100. |
max | number | Range maximum. Defaults to 100; invalid runtime ranges normalize to 0–100. |
label | ReactNode | Visible task name and one required accessible naming path. |
valueLabel | ReactNode | Optional visible completion text in the header. |
valueText | string | Optional localized aria-valuetext for richer completion context. |
aria-label | string | Required naming alternative when label is not rendered. |
aria-labelledby | string | Required external naming alternative when label is not rendered. |
root DOM props | div props | Forwards id, className, style, aria-describedby, aria-controls, events, and consumer data attributes to the progressbar root. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | Progress installs its Tailwind-first component, merge utility, token bridge, and residual progress keyframes. |
Base UI | No interactive primitive required. |
Server safety | Progress has no client boundary or runtime dependency. |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Progress communicates task completion only. Final success, failure, cancellation, and blocked outcomes belong to Alert, Badge, or Toast.
- Progress is not Meter: static scores, capacity, battery levels, and health values have a separate semantic responsibility.
Do / do not
Do
- Show determinate progress only when a reliable value exists.
- Use indeterminate Progress only while a reliable value is unavailable.
- Keep the task label specific and use valueText for meaningful completion text.
- Use Progress when completion feedback is useful to the person waiting.
Do not
- Invent values to make an operation appear active.
- Use Progress as a static score, capacity, battery, or health measurement.
- Encode a final success or failure only through indicator color.
- Use it as a Spinner or Skeleton replacement when those components fit better.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Layout | --n-progress-height / radius / gap / header-gap | Controls track shape and spacing. |
Text | --n-progress-label-* / --n-progress-value-* | Controls visible header text. |
Surfaces | --n-progress-track-background / --n-progress-indicator-background | Keeps the track neutral and the indicator aligned with the action accent. |
Motion | --n-progress-duration / easing / indeterminate-* | Controls transform transition, segment movement, and the reduced-motion position. |