Skip to content
THE COMPONENT LIBRARY
Skip to content

Component reference

CircularProgress

Show upload progress with a numeric value.

Preview

Live preview

Changes apply to this preview only.

Upload

The ring is small enough to sit next to a label, so the label stays outside.

design-system.zip68% · 4.2 MB of 6.1 MB

Quota

A success tone with the value read inside the ring.

Go used

Syncing

No known duration: the ring rotates and nothing is announced as a value.

Syncing…

Service health

Three small gauges, one tone per state, with their labels outside the ring.

API99%
CDN92%
Workers64%

Width adapts to the available space

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Sizes

The stroke scales with the diameter, because the whole SVG scales.

Open preview

Variants

The variant sets the tone of the indicator.

Open preview

States

Determinate, indeterminate, formatted, clamped.

Open preview

Usage

Use determinate progress for a known total and indeterminate presentation when the total is unknown.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluCircularProgressProps

Type source
PimoluCircularProgressProps public API
NameTypeDefaultDescription
valuenumber | undefined—Current value between 0 and `max`. Leave it undefined for an indeterminate gauge.
maxnumber | undefined100Upper bound.
size"sm" | "md" | "lg" | undefined"md"Visual size of the gauge.
variant"primary" | "secondary" | "neutral" | "success" | "warning" | "danger" | undefined"primary"Tone of the indicator.
labelstring | undefined—Accessible name of the gauge. It is not rendered: a circular gauge is too small to carry a readable label, so compose it next to the component.
showValueboolean | undefinedfalseDisplay the current value in the middle.
formatValue((value: number, max: number) => string) | undefined—Formats the readout, for example (value, max) => `${value}/${max}`.
valueLabelstring | undefined—Overrides the value announced by assistive technology.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefined—Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefined—Standard React/HTML attribute.
classNamestring | undefined—Standard React/HTML attribute.
styleCSSProperties | undefined—Standard React/HTML attribute.
aria-labelstring | undefined—Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLDivElement> | undefined—Standard React/HTML attribute.
value

number | undefined

No default extracted.

Current value between 0 and `max`. Leave it undefined for an indeterminate gauge.

max

number | undefined

Default: 100

Upper bound.

size

"sm" | "md" | "lg" | undefined

Default: "md"

Visual size of the gauge.

variant

"primary" | "secondary" | "neutral" | "success" | "warning" | "danger" | undefined

Default: "primary"

Tone of the indicator.

label

string | undefined

No default extracted.

Accessible name of the gauge. It is not rendered: a circular gauge is too small to carry a readable label, so compose it next to the component.

showValue

boolean | undefined

Default: false

Display the current value in the middle.

formatValue

((value: number, max: number) => string) | undefined

No default extracted.

Formats the readout, for example (value, max) => `${value}/${max}`.

valueLabel

string | undefined

No default extracted.

Overrides the value announced by assistive technology.

onChange

ChangeEventHandler<HTMLDivElement, Element> | undefined

No default extracted.

Standard React/HTML attribute.

defaultValue

string | number | readonly string[] | undefined

No default extracted.

Standard React/HTML attribute.

className

string | undefined

No default extracted.

Standard React/HTML attribute.

style

CSSProperties | undefined

No default extracted.

Standard React/HTML attribute.

aria-label

string | undefined

No default extracted.

Defines a string value that labels the current element.

onClick

MouseEventHandler<HTMLDivElement> | undefined

No default extracted.

Standard React/HTML attribute.

Accessibility

  • Provide an accessible label and a meaningful value or busy message.
Read the accessibility guide →