CircularProgress·component·@astryxdesign/labExperimental

Circular Progress

A circular progress indicator that shows completion as a ring or arc. Use it for upload progress, score displays, dashboard gauges, or compact progress where horizontal space is limited. Complements ProgressBar for radial layouts.

@astryxdesign/lab

Authored source examples

Source examples recorded in the documentation for this entry.

Determinate with value label

<CircularProgress value={75} label="Upload progress" hasValueLabel />

Indeterminate

<CircularProgress isIndeterminate label="Loading..." />

Custom value format

<CircularProgress value={3.2} max={5} label="Disk usage" hasValueLabel formatValueLabel={(v, m) => `${v} GB / ${m} GB`} />

Disabled

<CircularProgress value={30} label="Canceled" isDisabled hasValueLabel />

Usage

Pass a value for determinate progress; set isIndeterminate when the duration is unknown.
Show the value with hasValueLabel, or pass children for custom center content: an icon or short label.
Always provide a label, even though it is visually hidden by default; screen readers need it.
Use circular progress for long text labels; use ProgressBar instead, which has more room for label and value display.
Use an indeterminate CircularProgress for small inline loading states; Spinner is the inline indicator.

Typed props

Prop	Type and behavior
`value`	`number` · default 0 Current value. Ignored when isIndeterminate is true.
`max`	`number` · default 100 Maximum value.
`label`	`string` · required Accessible label for screen readers.
`isLabelHidden`	`boolean` · default true Visually hide the label (remains accessible). Defaults to true since circular progress typically shows center content instead.
`hasValueLabel`	`boolean` · default false Show the formatted value (e.g. "75%") in the center of the ring. Ignored when isIndeterminate is true or when children provide custom center content.
`formatValueLabel`	`(value: number, max: number) => string` Custom value label formatter; defaults to a percentage string.
`children`	`ReactNode` Content displayed in the center of the ring: percentage, icon, or custom content. Takes precedence over hasValueLabel.
`size`	`'sm' \| 'md' \| 'lg'` · default 'md' Diameter of the progress ring (32px, 48px, 64px).
`variant`	`'accent' \| 'success' \| 'warning' \| 'error' \| 'neutral'` · default 'accent' Semantic color variant for the progress fill.
`isIndeterminate`	`boolean` · default false Animated spinning indicator for unknown progress. Respects prefers-reduced-motion by slowing the animation.
`isDisabled`	`boolean` · default false Visually disabled: grays out the ring and text. Use for canceled or inactive operations.
`xstyle`	`StyleXStyles` StyleX styles for layout customization (margins, positioning). Must be a stylex.create() value.

Theming

Targets

astryx-circular-progress

Visual props: variant, size

astryx-circular-progress-track

astryx-circular-progress-fill

Visual props: variant