# ProgressCircle

> A circular progress indicator, determinate or indeterminate.

Category: Feedback · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/progress-circle

Use ProgressCircle where a bar does not fit: inside cards, next to file names or for compact completion scores. It needs an accessible name from aria-label or aria-labelledby.

## Import

```tsx
import { ProgressCircle } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { ProgressCircle } from '@bindshq/stance-react';

export function Basic() {
  return <ProgressCircle aria-label="Profile completeness" value={75} showValue />;
}
```

### Sizes

```tsx
import { ProgressCircle } from '@bindshq/stance-react';

export function Sizes() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
      <ProgressCircle aria-label="Small" value={40} size="sm" />
      <ProgressCircle aria-label="Medium" value={60} size="md" showValue />
      <ProgressCircle aria-label="Large" value={80} size="lg" showValue />
    </div>
  );
}
```

### Custom centre content and tone

```tsx
import { ProgressCircle } from '@bindshq/stance-react';

export function Custom() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
      <ProgressCircle
        aria-label="Seats used"
        value={46}
        max={50}
        size={96}
        tone="warning"
        formatValue={(v, m) => `${v} of ${m} seats`}
      >
        46/50
      </ProgressCircle>
      <ProgressCircle
        aria-label="Deployment complete"
        value={100}
        size="lg"
        tone="success"
        showValue
      />
    </div>
  );
}
```

### Indeterminate

```tsx
import { ProgressCircle } from '@bindshq/stance-react';

export function Indeterminate() {
  return <ProgressCircle aria-label="Verifying domain" />;
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ProgressCircle | `value` | `number \| null` | None | Current value; null or omitted is indeterminate. |
| ProgressCircle | `max` | `number` | `100` | Maximum value. |
| ProgressCircle | `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | 32, 48, 72px or a custom pixel size. |
| ProgressCircle | `thickness` | `number` | None | Ring thickness in px. |
| ProgressCircle | `tone` | `'default' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Indicator colour. |
| ProgressCircle | `showValue` | `boolean` | `false` | Show the value in the centre. |
| ProgressCircle | `formatValue` | `(value: number, max: number) => string` | `percentage` | Value text. |
| ProgressCircle | `children` | `ReactNode` | None | Custom centre content (visual only). |

## Accessibility

- role="progressbar" with value attributes and aria-valuetext.
- Centre content is aria-hidden, since the value is already announced through aria-valuetext.
- Always provide aria-label or aria-labelledby.

## Guidelines

**Do**

- Use md or larger when showing the value inside.

**Don’t**

- Use as a decorative spinner; use Spinner.

## Related

- https://stanceui.com/components/progress
- https://stanceui.com/components/spinner