Progress
Measured task progress in a bar or compact ring.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.
Usage
import { ProgressBar } from '@commenda/pathfinder/progress';
<ProgressBar
label="Uploading documents"
value={40}
helperText="107 of 256 files"
/>;API reference
| Prop | Type | Default / behavior |
|---|---|---|
label | string | Required stable task name |
value | number | null | Required; null is indeterminate |
max | number | 100; invalid maxima normalize to 100 |
status | active | complete | failed | active; complete requires numeric value |
size (bar) | sm | md | sm: 4 px; md: 8 px |
size (ring) | 16 | 24 | 32 | 16 |
helperText | string | Bar count or failure explanation |
hideLabel | boolean | false; accessible name stays |
showValue | boolean | true for determinate bars |
valueText | string | Optional human-readable ARIA value |
Clamp values to 0–max; nonfinite numeric values become 0. Reaching max does not confirm success: explicitly set status="complete". Failure retains its last measured value. The application owns monotonic updates, task identity, retry and cancellation. ProgressRing retains its previous status-icons import path and accepts continuous values. Use a chart or meter for quotas and budgets.
Examples
Statuses
Sizes
Ring
Read the design guidance before using these components.
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Progress — 269:2
- PROGRESS-01: Long measured tasks such as upload, import, export or sync. Bar for one task; ring for a completion count beside text. Never use progress for budgets, limits or quotas.
- PROGRESS-02: Keep the task label stable, and put counts or the current step in helper text. Avoid backwards progress and reaching 100% while still waiting. Success is explicit; numeric max alone does not confirm it.
- PROGRESS-03: Failure preserves its last measured value, turns red and explains the problem; the application offers Retry. Offer cancellation for long work and explain what happens to completed work. Use null for unknown length, then switch to measured values when available.
- PROGRESS-04: Bar heights 4 by default or 8 for a page's main task. Track pearl 300/full radius; active blue 700, complete green 700, failed red 700. Label/13 Strong, value Label/13 pearl 800, helper Copy/12 pearl 800 or red 800; gaps 8, status icon 16 with gap 6. Value changes ease out over 300 ms. Indeterminate segment is 30% and loops linearly over 1.2 seconds. Reduced motion removes spatial loops. Ring sizes 16/24/32 retain the source geometry and accept continuous counts.
Explicit differences and boundaries
- Progress: compose the existing 16px ProgressRing for the Figma ring pattern.
TableCellalso offers a linear progress renderer; these are named alternatives, not interchangeable artwork.