Progress
Shows how much of a task is complete—usually as a horizontal progress bar.
Displays completion state for a task. Progress uses BY styling: a rounded track (bg-neutral-alpha-4) and accent indicator (bg-accent-9). Control completion with value and max (default 100). Use size for bar height.
Installation
The component is exported from @by/experience-system. Add the package with your package manager:
pnpm add @by/experience-systemIn this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.
Composition
Use the following composition to render a Progress bar:
ProgressProgress is a single-export root that renders the indicator part internally. Behavior follows Radix Progress.
Usage
import { Progress } from '@by/experience-system';Progress is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router. Pair with Field and FieldLabel to associate a visible label with the bar.
<Progress value={66} max={100} size="medium" />Examples
Sizes
size adjusts track height: small, medium (default), or large.
API Reference
The single export maps to Radix UI Progress. The table below mirrors the upstream API in full; the indicator is rendered internally and inherits the same data attributes.
Progress
Progress is the Radix Progress.Root with Experience System styling and a size variant. Omit value (or pass null) to show an indeterminate bar.
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
value | number | null | No default value (null = indeterminate) |
max | number | 100 |
getValueLabel | (value: number, max: number) => string | No default value |
size | enum | "medium" (experience system: "small" | "medium" | "large") |
| Data attribute | Values |
|---|---|
[data-state] | "complete" | "indeterminate" | "loading" |
[data-value] | The current value |
[data-max] | The max value |
The indicator inherits the same [data-state], [data-value], and [data-max] attributes and is exposed via [data-slot="progress-indicator"] for custom selectors.
Accessibility
The root exposes role="progressbar". aria-valuenow, aria-valuemin, and aria-valuemax reflect value and max when progress is determinate. Provide getValueLabel when the default value text should be customized for screen readers, and pair the bar with a visible label (for example via Field / FieldLabel) so the meaning is clear.
Source in the repo: packages/experience-system/src/components/Progress/Progress.tsx and variants.ts. Agent-oriented contracts: packages/experience-system/src/components/Progress/Progress.instructions.md.