# Progress

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/progress
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=269-2

```tsx
import { ProgressBar } from '@commenda/pathfinder/progress';
<ProgressBar
  label="Uploading documents"
  value={40}
  helperText="107 of 256 files"
/>;
```


## Installation [#installation]

```sh
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 [#usage]

```tsx
import { ProgressBar } from '@commenda/pathfinder/progress';
<ProgressBar
  label="Uploading documents"
  value={40}
  helperText="107 of 256 files"
/>;
```

## API reference [#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 [#examples]

### Statuses [#statuses]


```tsx
<>
  <ProgressBar
    label="Uploading documents"
    value={40}
    helperText="107 of 256 files"
  />
  <ProgressBar
    label="Uploading documents"
    value={100}
    status="complete"
    helperText="All files uploaded"
  />
  <ProgressBar
    label="Uploading documents"
    value={40}
    status="failed"
    helperText="Connection lost. Try again."
  />
  <ProgressBar
    label="Preparing export"
    value={null}
    helperText="Calculating file count"
  />
</>;
```


### Sizes [#sizes]


```tsx
<>
  <ProgressBar
    label="Uploading documents"
    value={40}
    size="md"
    helperText="107 of 256 files"
  />
  <ProgressBar label="Uploading documents" value={40} />
</>;
```


### Ring [#ring]


```tsx
import { ProgressRing } from '@commenda/pathfinder/progress';
<>
  {([16, 24, 32] as const).map((size) => (
    <ProgressRing
      key={size}
      size={size}
      label="Documents uploaded"
      value={3}
      max={9}
      valueText="3 of 9 documents"
    />
  ))}
  <span>3 of 9 documents</span>
</>;
```


Read the [design guidance](/docs/components/progress#design-rules) before using these components.

## Design rules [#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--2692]

- **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 [#explicit-differences-and-boundaries]

- **Progress:** compose the existing 16px ProgressRing for the Figma ring pattern. `TableCell` also offers a linear progress renderer; these are named alternatives, not interchangeable artwork.