# Progress ring (goodtabs UI)

A circular progress indicator drawn with one circle and two numbers.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/progress-ring.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/progress-ring`

## Usage

```tsx
import { ProgressRing } from "@/components/ui/progress-ring"

<ProgressRing label="Upload progress" value={70} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string` |  | Accessible name for the progressbar. |
| value | `number` |  | Current value. |
| max | `number` | `100` | The value that means done. |
| size | `number` | `64` | Outer diameter in px. |
| stroke | `number` | `4` | Stroke width in px. |
| children | `ReactNode` |  | Centre content. Defaults to the percentage. |

## When to use

- Compact progress in a card, avatar or list row
- Goals and quotas where the share of a whole matters
- Anywhere a bar is too wide

## When not to use

- Indeterminate loading, use a spinner or a progress bar
- Several values compared side by side, use a bar chart

## Notes for agents

- Server component. The ring starts at the top and fills clockwise
- The radius is (size - stroke) / 2 so the stroke never clips the box
- Colours come from foreground tones; wrap it in text-brand only if you add a mark yourself
- The offset eases over 200ms and the transition is off under reduced motion

## The maths

- Radius r = (size - stroke) / 2, so a 24px ring with a 2px stroke has r = 11.
- Circumference 2πr = 69.12 is the dasharray.
- Dashoffset 2πr × (1 - p) = 69.12 × 0.3 = 20.73 at 70 percent.

Docs: https://ui.goodtabs.co/components/progress-ring