Progress Circle
Circular progress indicator showing completion percentage.
Installation
npx paubha@latest add progress-circleUsage
import { ProgressCircle } from "@/components/ui/progress-circle";
<ProgressCircle value={75} aria-label="Upload progress" />Examples
Sizes
Without the percentage label
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | — | Current progress value, from 0 to max. |
| max | number | 100 | Maximum value. |
| size | "sm" | "md" | "lg" | "md" | Circle diameter. |
| showPercentage | boolean | true | Shows the percentage as text in the center. |
| aria-label | string | — | Required. Describes what is loading, since the value is conveyed via ARIA, not the visual arc. |
Accessibility
Accessibility
Role.
role="progressbar"witharia-valuenow,aria-valuemin="0", andaria-valuemax="100"(or your custommax).Label. Always pass
aria-labeldescribing what is loading, since the circular rendering itself is purely decorative and conveys nothing to assistive tech on its own.
When to use
Use for circular progress: skill completion, dashboard metrics, timer countdowns. Works well in compact spaces where a linear bar would be too wide.
Do:
- Display the value in the center
- Use consistent sizing
- Animate smoothly as the value changes
Don't:
- Use below 32px (the percentage text becomes unreadable)
- Show multiple sizes in the same row
- Use for indeterminate loading, use Spinner instead
Related components
- Progress Bar: for linear progress
- Spinner: for indeterminate loading
- Badge: for static metric display