CircularProgress

Ring-shaped progress indicator for uploads, downloads, and goal-completion states.

stable
since v0.1.0
1.3 kB
data-display
progress
feedback

Preview

tsx

import { CircularProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
      <CircularProgress value={25} />
      <CircularProgress value={50} />
      <CircularProgress value={75} />
      <CircularProgress value={100} />
    </div>
  );
}

Usage

import { CircularProgress } from '@arshad-shah/cynosure-react';

<CircularProgress value={60} />

For custom layouts (overlaid badges, multi-ring visualisations) compose with CircularProgressRoot, CircularProgressTrack, CircularProgressIndicator, and CircularProgressLabel directly.

Sizes

Five sizes are available: xs, sm, md (default), lg, and xl.

Preview

Open

tsx

import { CircularProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '1.25rem', alignItems: 'center' }}>
      <CircularProgress value={60} size="xs" />
      <CircularProgress value={60} size="sm" />
      <CircularProgress value={60} size="md" />
      <CircularProgress value={60} size="lg" />
      <CircularProgress value={60} size="xl" />
    </div>
  );
}

Color schemes

Pick a scheme that matches the surrounding context: accent, success, warning, danger, or neutral.

Preview

Open

tsx

import { CircularProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '1.25rem', alignItems: 'center' }}>
      <CircularProgress value={70} colorScheme="accent" />
      <CircularProgress value={70} colorScheme="success" />
      <CircularProgress value={70} colorScheme="warning" />
      <CircularProgress value={70} colorScheme="danger" />
      <CircularProgress value={70} colorScheme="neutral" />
    </div>
  );
}

With label

Pass children to render centered content — typically a percentage or a short label.

Preview

Open

tsx

import { CircularProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '1.5rem', alignItems: 'center' }}>
      <CircularProgress value={42} size="lg">
        <span style={{ fontWeight: 600, fontSize: '0.875rem' }}>42%</span>
      </CircularProgress>
      <CircularProgress value={100} size="lg" colorScheme="success">
        <span style={{ fontWeight: 600, fontSize: '0.875rem' }}>Done</span>
      </CircularProgress>
    </div>
  );
}

Indeterminate

Pass indeterminate for an unknown-duration loader. The ARIA value attributes are dropped so assistive tech announces an unspecified loading state.

Preview

Open

tsx

import { CircularProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '1.5rem', alignItems: 'center' }}>
      <CircularProgress indeterminate size="md" aria-label="Loading" />
      <CircularProgress indeterminate size="lg" colorScheme="success" aria-label="Loading" />
    </div>
  );
}

API

PropTypeDefaultDescription

value

number

Current progress value (0–`max`). Ignored when `indeterminate` is true.

max

number

100

Upper bound used to compute the filled arc percentage.

size

"xs"|"sm"|"md"|"lg"|"xl"

Preset diameter token (e.g. `sm`/`md`/`lg`). Maps to a fixed pixel size in the CSS.

colorScheme

"accent"|"success"|"warning"|"danger"|"neutral"

accent

Indicator colour role: `accent` (brand), `success`, `warning`, `danger`, or `neutral`.

thickness

number

Stroke width of both track and indicator, in pixels.

indeterminate

boolean

false

Render the looping spinner animation instead of a value-driven arc.

completionState

"auto"|"none"

auto

Override completion-state styling: `auto` flips to success colours once `value === max`; `error` paints the danger colour scheme regardless.

children

ReactNode

—

Centered content — typically the percentage or a short label.

aria-label

string

—

Accessible label for screen readers when no visible label is supplied.

className

string

—

Additional class applied to the root element.

style

CSSProperties

—

Additional inline styles merged onto the root.

Accessibility

Renders role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax.
Sets aria-valuetext to a formatted percentage so screen readers announce a human-readable value.
Omits the value when indeterminate is set so assistive tech reports “loading” instead.
Provide an aria-label when the ring is the only feedback on screen.
data-complete is exposed on the root once value >= max (unless completionState="none"), letting you style the finished state.

Recipes

Use value for deterministic progress (uploads, downloads); pass indeterminate for spinner-style loaders.
Tune thickness to make the ring beefier on dark surfaces or thinner inside dense dashboards.
Combine colorScheme="success" with the default completionState="auto" for a green finished-state at 100%.
Pair with Stat to render a metric inside the ring’s centre via CircularProgressLabel.