Progress
Progress indicators show that work is underway, either as a bar or a spinner.
Puzzle provides two progress indicators: LinearProgress for a horizontal bar and CircularProgress for a spinner. Both are determinate when given a value and indeterminate when value is omitted.
Import
import { LinearProgress, CircularProgress } from "@puzzle-ui/ui";Linear progress
Determinate
Pass value as a number from 0 to 100.
Indeterminate
Omit value when the duration is unknown.
Color and track
Use color to override the primary color with any CSS color value, and showTrack={false} to hide the background track.
Circular progress
Determinate
Indeterminate
Omit value to show a continuously spinning indicator.
Size
Use size (sm, md, lg) to scale the spinner. The default is md.
API reference
Shared props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | Progress from 0 to 100. When omitted, the indicator is indeterminate. |
color | string | var(--puzzle-color-primary) | CSS color of the indicator and track. |
showTrack | boolean | true | Shows the background track behind the indicator. |
LinearProgress props
LinearProgress accepts the shared props and the props of <div>, which are passed to the track element. className and style are merged with the component's own; your style takes precedence.
CircularProgress props
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "md" | "lg" | "md" | Diameter of the spinner. |
CircularProgress also accepts the shared props and the props of <svg>. Its aria-label defaults to "Loading...".
TypeScript types
The package exports ProgressProps, LinearProgressProps, CircularProgressProps, and CircularProgressSize.
Theming
Both indicators default to --puzzle-color-primary, so they follow light, dark, and scoped themes. Animation is handled in CSS.
Accessibility
- Both components render
role="progressbar"witharia-valuemin="0"andaria-valuemax="100". Determinate indicators also setaria-valuenow; indeterminate ones omit it, as the specification requires. valueis clamped to0–100; non-finite values are treated as indeterminate.- Always provide an accessible name with
aria-labeloraria-labelledby. - CircularProgress sets
aria-label="Loading..."by default; override it with a more specific label, such as the task being performed. - For long-running or important operations, also announce completion in a live region so assistive technology users know when work finishes.