# Circular Progress (`circular-progress`) - SignalOS widget

> Pure-SVG radial gauge with a center label, token-driven colors, and progressbar semantics.

- **Version:** 0.1.0
- **Kind:** widget · **Category:** data-display
- **Install:** `npx shadcn@latest add @signalos/circular-progress`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils
- **npm dependencies:** none
- **Files installed:** `src/components/widgets/circular-progress/CircularProgress.tsx`, `src/components/widgets/circular-progress/CircularProgress.types.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { CircularProgress } from "@/components/widgets/circular-progress/CircularProgress"
```

## Example

```tsx
// Example: status-colored gauges with custom labels.
import { CircularProgress } from "@/components/widgets/circular-progress/CircularProgress"

export default function Example() {
  return (
    <div className="flex items-end gap-8">
      <div className="flex flex-col items-center gap-2">
        <CircularProgress
          value={96}
          size={72}
          strokeWidth={6}
          colorClass="text-success-500"
        />
        <span className="text-stat-label text-muted-foreground">SLA</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <CircularProgress
          value={64}
          size={72}
          strokeWidth={6}
          colorClass="text-warning-500"
        />
        <span className="text-stat-label text-muted-foreground">Coverage</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        {/* Custom center label instead of a percentage: */}
        <CircularProgress
          value={88}
          size={72}
          strokeWidth={6}
          formatLabel={(v) => `${(v / 100).toFixed(2)}`}
        />
        <span className="text-stat-label text-muted-foreground">
          Confidence
        </span>
      </div>
    </div>
  )
}
```

## Props

### `CircularProgressProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `number` | yes | - | Progress value from 0 to 100. |
| `size` | `number \| undefined` | no | `40` | Diameter of the gauge in pixels. |
| `strokeWidth` | `number \| undefined` | no | `4` | Stroke width of the arc in pixels. |
| `showLabel` | `boolean \| undefined` | no | `true` | Whether to render the numeric label in the center. |
| `formatLabel` | `((value: number) => string) \| undefined` | no | - | Custom formatter for the center label. Defaults to `${value}%`. |
| `colorClass` | `string \| undefined` | no | `"text-primary"` | Tailwind text-* class driving the arc color (uses stroke-current). |
| `className` | `string \| undefined` | no | - |  |

## Changelog

# circular-progress

## 0.1.0

- Initial release, lifted from `signal-core-ui` `CircularProgress`.
- Default arc color changed from `text-teal-500` to token-backed `text-primary`.
- Added `showLabel`, `formatLabel`, value clamping, and `role="progressbar"` semantics.