# SvCircularProgress
A circular ring progress indicator - determinate or spinning - with color
intents, sizing and thickness, and an optional center label or custom center
content.
`SvCircularProgress` is the ring form of [SvProgress](https://svgrid.com/docs/help/ui-components/sv-progress/): a
WAI-ARIA `progressbar` drawn as an SVG arc. Use it for compact completion
readouts in cards, buttons, and dashboards. Leave `value` off and set
`indeterminate` for a continuous spinner. Colors come from the grid's `--sg-*`
tokens, and the spin animation respects `prefers-reduced-motion`.
Related: [SvProgress](https://svgrid.com/docs/help/ui-components/sv-progress/) · [SvGauge](https://svgrid.com/docs/help/ui-components/sv-gauge/) · [Range & meters overview](https://svgrid.com/docs/help/ui-components/range/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvCircularProgress` starter into your app:
Prefer to see it first? `npx @svgrid/ui try circular-progress` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvCircularProgress` ships free in
`@svgrid/grid` (dependency-free):
The examples on this page import from `@svgrid/grid`:
```svelte
```
```ts
import { SvCircularProgress } from '@svgrid/grid'
```
## Example
> Live demo: Progress (linear + circular) - https://svgrid.com/demos/330-progress/
```svelte
```
## Props
| Prop | Type | Default | Description |
| --------------- | --------------------------------------------- | -------- | ------------------------------------------------------------- |
| `value` | `number` | `0` | Current value, `0..max`. Ignored when `indeterminate`. |
| `max` | `number` | `100` | Value that represents a full ring. |
| `indeterminate` | `boolean` | `false` | Continuous spinning arc; drops the value ARIA. |
| `size` | `number` | `48` | Diameter in px. |
| `thickness` | `number` | `5` | Ring stroke width in px. |
| `color` | `accent` \| `success` \| `warning` \| `danger` | `accent` | Arc intent, mapped to `--sg-*` tokens. |
| `showLabel` | `boolean` | `false` | Percentage label in the center (determinate only). |
| `formatLabel` | `(value, max) => string` | - | Custom label text; defaults to rounded percent. |
| `ariaLabel` | `string` | - | Accessible name for the progressbar. |
| `children` | `Snippet` | - | Custom center content; overrides `showLabel`. |
## Examples
### Percentage ring
The default center label shows a rounded percent. Size and thickness scale it to
fit a card or a KPI tile:
```svelte
```
### Custom center content
Pass a `children` snippet to put anything in the middle - an icon, a fraction,
or a stacked label - instead of the percent:
```svelte
4/5
```
### Inline spinner
Set `indeterminate` at a small size for a button or toolbar busy indicator:
```svelte
```
### Countdown ring
Bind `value` to a ticking count and the arc shrinks as time runs out; a
`children` snippet shows the seconds left, and `color` turns danger near zero:
```svelte
{left}s
```
Tip: a `children` snippet overrides `showLabel`, so put the fraction or countdown
in the snippet and leave `showLabel` off.
## Accessibility
- Renders `role="progressbar"` with `aria-valuemin` / `aria-valuemax` /
`aria-valuenow` and an `aria-valuetext` label when determinate.
- Indeterminate mode omits the value attributes so it announces as busy.
- Set `ariaLabel` to name the task; custom `children` are visual only.
## Sizes
Every control takes the same three sizes, so a dense toolbar and a roomy form can share components.
```svelte
```
## See also
- [Feedback overview](https://svgrid.com/docs/help/ui-components/feedback/) - the status and feedback family at a glance.
- [SvProgress](https://svgrid.com/docs/help/ui-components/sv-progress/) - the linear bar form of the same control.
- [SvGauge](https://svgrid.com/docs/help/ui-components/sv-gauge/) - a radial dial for a measured value.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-circular-progress/ . All docs: https://svgrid.com/llms.txt