# SemiCircleProgress
- **Category:** Feedback (`feedback`)
- **Slug:** `feedback/semi-circle-progress`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { SemiCircleProgress } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/feedback/semi-circle-progress
> A half-ring gauge drawn as a hand-rolled SVG arc, with a mono centre value and optional caption.
## When to use it
A semicircle gauge reads as a dashboard dial: capacity, usage, a score out of a known maximum. It occupies half the vertical space of a full **RadialProgress** ring, which makes it a natural fit at the top of a **StatCard** or in a compact tile.
The accent is the default arc color — the reserved brand signal for a single live value. Only reach for `tone` when the value crossing a threshold is itself the message (capacity in the red). It's a display gauge, not a control, so it renders on the server with no interactivity.
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `caption` | `ReactNode` | no | — | Optional mono-UPPER caption under the value. |
| `className` | `string` | no | — | — |
| `formatValue` | `((value: number, max: number) => ReactNode)` | no | — | Format the centre value. Defaults to a rounded percentage of `max`. |
| `label` | `string` | no | — | Accessible label describing what the gauge measures. |
| `max` | `number` | no | `100` | Upper bound of `value`. |
| `showValue` | `boolean` | no | `true` | Render the centre value label. |
| `size` | `number` | no | `160` | Full width of the gauge in px. |
| `style` | `CSSProperties` | no | — | — |
| `thickness` | `number` | no | `10` | Arc stroke width in px. |
| `tone` | `enum` | no | — | Swap the accent arc for a status tone. |
| `value` | `number` | yes | — | Current value. |
## Examples
### Basics
Pass a `value` (and a `max` if not out of 100). The arc sweeps left to right over the top semicircle in the accent, above a faint track. The centre renders a mono tabular percentage by default; add a `caption` for a mono-UPPER unit label.
```tsx
import { SemiCircleProgress } from "@protocore/pds";
export default function SemiCircleProgressBasics() {
return (
);
}
```
### Tones and sizing
`tone` swaps the accent arc for a status color when the reading itself carries meaning — a near-full capacity gauge in `danger`. `size` and `thickness` scale the geometry; `formatValue` customises the centre label.
```tsx
import { SemiCircleProgress } from "@protocore/pds";
export default function SemiCircleProgressTones() {
return (
`${v}/${m}`}
caption="Steps"
/>
);
}
```
## Usage
**Do**
- Use it for a value against a known maximum (capacity, score, usage).
- Keep the accent arc for a neutral reading; it's the live-value signal.
- Add a `caption` to name the unit the number measures.
- Reach for `tone` only when crossing a threshold is the point.
**Don't**
- Use it for indeterminate progress; that's a Spinner.
- Stack many tones in one view; the accent should stay reserved.
- Omit `label`; the gauge needs an accessible name.
## Accessibility
**Notes**
- Exposes `role="progressbar"` with `aria-valuenow/min/max` and an `aria-label` from the `label` prop.
- The SVG arc and centre label are `aria-hidden`; the value is conveyed through the ARIA attributes so it isn't announced twice.
## Related
`radial-progress`, `progress-bar`, `stat-card`, `sparkline`
---
© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/