/// Charts

RadialProgress

A single-value radial gauge — a hand-rolled SVG ring with an accent (or tone) value arc and a mono tabular centre label.

import { RadialProgress } from "@protocore/pds";

View as Markdown

Import path

Unlike the recharts wrappers, RadialProgress is a hand-rolled SVG gauge with no chart dependency, so it ships from the main entry:

import { RadialProgress } from "@protocore/pds";

Basics

Pass a value (and max, defaulting to 100). The arc fills clockwise from 12 o'clock in the accent — the reserved brand signal for a single live figure — over a faint track, with a mono tabular percentage in the centre. The ring is the one place a radius is on-brand: it's a gauge, not a control.

Tones, captions, and custom labels

A tone swaps the accent arc for a status colour when the gauge itself reports health (danger for near-full disk, success for uptime). Add a mono-UPPER caption under the number, and override formatValue to print a fraction (3/5) or a raw value instead of a percentage.

When to use it

Use RadialProgress for a *single* value against a bound where the compact ring earns its place — a KPI tile, a quota gauge, the centre of a DonutChart, a sync/uptime readout. It draws the eye to one number.

For a value in a row or a dense list, a thin ProgressBar reads faster and packs tighter. For a whole split into parts, use a PercentageBarChart. RadialProgress is determinate only — for unknown-duration work use an indeterminate ProgressBar or a Spinner.

Usage

Use it for one headline value against a clear bound.
Keep the accent arc for neutral progress; switch to a `tone` only when the value reports health.
Pair it with a mono caption so the number's meaning is unambiguous.
Nest it in a DonutChart's hole to show a part-to-whole plus its total.

Don't

Don't use it for indeterminate work — it's determinate; reach for a Spinner.
Don't crowd a table row with rings; a ProgressBar packs tighter.
Don't spend the accent arc on a status meaning — use a `tone` for that.
Don't rely on the arc alone; the centre label carries the exact value.

Accessibility

Exposes `role="progressbar"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`; pass a `label` describing what it measures.
The SVG ring and centre label are decorative (aria-hidden) — the value is announced through the progressbar semantics.
Out-of-range values are clamped into `[0, max]` so the arc and reported value stay honest.

`RadialProgress` props

Prop	Type	Default	Description
`caption`	`ReactNode`	—	Optional mono-UPPER caption rendered under the value.
`className`	`string`	—
`formatValue`	`((value: number, max: number) => ReactNode)`	—	Format the centre value label. Defaults to a rounded percentage of `max`.
`label`	`string`	—	Accessible label describing what the gauge measures.
`max`	`number`	`100`	Upper bound of `value`. Defaults to `100`.
`showValue`	`boolean`	`true`	Render the centre value label. Defaults to `true`.
`size`	`number`	`120`	Diameter in px. Defaults to `120`.
`style`	`CSSProperties`	—
`thickness`	`number`	`8`	Ring stroke width in px. Defaults to `8`.
`tone`	`enum`	—	Swap the accent arc for a status tone.
`value` *	`number`	—	Current value.