> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ProgressRing

> Show measured or indeterminate progress in a compact circular indicator.

export const StoryEmbed = ({storyId, title, height = 120}) => <>
    <Tabs>
      <Tab title="Light">
        <iframe title={`${title} (light)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:light`} width="100%" height={height} loading="lazy" allow="clipboard-write" style={{
  border: 0
}} />
      </Tab>
      <Tab title="Dark">
        <iframe title={`${title} (dark)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:dark`} width="100%" height={height} loading="lazy" allow="clipboard-write" style={{
  border: 0
}} />
      </Tab>
    </Tabs>
    <a href={`https://storybook.twenty.com/?path=/story/${storyId}`}>
      Open in Storybook
    </a>
  </>;

`ProgressRing` supplies a circular appearance for [Progress](/ui/primitives/feedback/progress). It shares the root's custom range, null, formatting, labeling, native prop, ref, and render contract. Optional children display a preformatted value beside the ring.

<StoryEmbed storyId="ui-feedback-progressring-progressring--display" title="Progress ring example" height={90} />

## Usage

Supply the raw controlled value and an accessible name. Use `aria-valuetext` when a formatted value explains progress more clearly than a percentage.

```tsx theme={null}
import { ProgressRing } from 'twenty-ui/primitives/feedback';

export const ImportProgress = () => (
  <ProgressRing
    value={600}
    max={1000}
    aria-label="Importing records"
    aria-valuetext="600 of 1,000 records"
  >
    600 / 1,000
  </ProgressRing>
);
```

Use `aria-labelledby` to associate the ring with an existing visible label, or compose `Progress.Label` as a child. Preformatted children do not automatically provide the ring's accessible name.

## Controlled progress and ranges

The application calculates `value` and formats display content. The ring does not fetch data, advance progress, or calculate quotas. `min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for semantic values and arc geometry. The arc fills by the normalized percentage, including when the minimum is nonzero.

<StoryEmbed storyId="ui-feedback-progressring-progressring--custom-range" title="Circular progress in a custom range" height={90} />

Pass `value={null}` for indeterminate progress. The ring omits `aria-valuenow` and displays an indeterminate arc. Non-finite values also remain indeterminate; they do not become zero or completion. Display content stays controlled by the application.

Use `locale`, `format`, and `getAriaValueText` as described in [Progress](/ui/primitives/feedback/progress). Compose `Progress.Value` to display the root's formatted value.

Use [ProgressBar](/ui/primitives/feedback/progress-bar) for horizontal progress or [MetricRow](/ui/components/data-display/metric-row) for a label and aligned value.

## Appearance and composition

`size="md"` renders a 16px ring; `size="sm"` renders a 14px ring. Both use a 2px stroke and fill clockwise from the top. `barColor` accepts CSS colors, including theme variables. The SVG is decorative and hidden from accessibility APIs.

Value changes animate for 300ms. Reduced-motion preferences disable the transition and indeterminate rotation. Native attributes, `className`, `style`, and `ref` target the outer progress element. `className` and `style` can receive the progress state. `render` can replace the root while retaining its semantics.

## Props

<ParamField body="aria-label" type="string">
  Accessible name identifying the measured operation.
</ParamField>

<ParamField body="aria-labelledby" type="string">
  ID of the visible label that names the operation.
</ParamField>

<ParamField body="aria-valuetext" type="string">
  Human-readable progress value overriding the default formatted value.
</ParamField>

<ParamField body="barColor" type="string">
  CSS color of the filled arc. Defaults to the blue theme color.
</ParamField>

<ParamField body="children" type="ReactNode">
  Optional preformatted value or Progress parts displayed before the ring.
</ParamField>

<ParamField body="className" type="string | ((state: ProgressRootState) => string | undefined)">
  Class applied to the progress root, or a callback receiving its status.
</ParamField>

<ParamField body="format" type="NumberFormatOptions">
  Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
</ParamField>

<ParamField body="getAriaValueText" type="((formattedValue: string, value: number | null) => string)">
  Receives the formatted value and raw value, including null, and returns an accessible value description.
</ParamField>

<ParamField body="locale" type="LocalesArgument">
  Locale or locale list used to format the value. Defaults to the runtime locale.
</ParamField>

<ParamField body="max" type="number" default="100">
  Inclusive maximum. Defaults to 100.
</ParamField>

<ParamField body="min" type="number" default="0">
  Inclusive minimum. Defaults to 0.
</ParamField>

<ParamField body="ref" type="Ref<HTMLDivElement>">
  Ref to the root div, or the element composed through render.
</ParamField>

<ParamField body="render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>">
  Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.
</ParamField>

<ParamField body="size" type="&#x22;md&#x22; | &#x22;sm&#x22;" default="md">
  Ring diameter: sm (14px) or md (16px). Defaults to md.
</ParamField>

<ParamField body="style" type="CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)">
  Inline styles applied to the progress root, or a callback receiving its status.
</ParamField>

<ParamField body="value" type="number | null" required>
  Controlled value in the min/max range. Use null for indeterminate progress.
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.