# Progress - Circular

URL: https://ark-ui.com/docs/components/progress-circular
LLM: https://ark-ui.com/llms.txt/components/progress-circular

An element that shows either determinate or indeterminate progress.

---



## Anatomy



```tsx
<Progress.Root>
  <Progress.Label />
  <Progress.ValueText />
  <Progress.Circle>
    <Progress.CircleTrack />
    <Progress.CircleRange />
  </Progress.Circle>
</Progress.Root>
```

## Examples

```tsx
import { Progress } from '@ark-ui/react/progress'
import styles from 'styles/progress-circular.module.css'

export const Basic = () => (
  <Progress.Root className={styles.Root} defaultValue={42}>
    <div className={styles.CircleContainer}>
      <Progress.Circle className={styles.Circle}>
        <Progress.CircleTrack className={styles.CircleTrack} />
        <Progress.CircleRange className={styles.CircleRange} />
      </Progress.Circle>
      <Progress.ValueText className={styles.ValueText} />
    </div>
  </Progress.Root>
)
```

### Min and Max

By default, the maximum is `100`. If that's not what you want, you can easily specify a different bound by changing the
value of the `max` prop. You can do the same with the minimum value by setting the `min` prop.

For example, to show the user a progress from `10` to `30`, you can use:

```tsx
import { Progress } from '@ark-ui/react/progress'
import styles from 'styles/progress-circular.module.css'

export const MinMax = () => (
  <Progress.Root className={styles.Root} defaultValue={20} min={10} max={30}>
    <div className={styles.CircleContainer}>
      <Progress.Circle className={styles.Circle}>
        <Progress.CircleTrack className={styles.CircleTrack} />
        <Progress.CircleRange className={styles.CircleRange} />
      </Progress.Circle>
      <Progress.ValueText className={styles.ValueText} />
    </div>
  </Progress.Root>
)
```

### Indeterminate

The progress component is determinate by default, with the value and max set to 50 and 100 respectively. To render an
indeterminate progress, you will have to set the `value` to `null`.

```tsx
import { Progress } from '@ark-ui/react/progress'
import styles from 'styles/progress-circular.module.css'

export const Indeterminate = () => (
  <Progress.Root className={styles.Root} defaultValue={null}>
    <div className={styles.CircleContainer}>
      <Progress.Circle className={styles.Circle}>
        <Progress.CircleTrack className={styles.CircleTrack} />
        <Progress.CircleRange className={styles.CircleRange} />
      </Progress.Circle>
      <Progress.ValueText className={styles.ValueText} />
    </div>
  </Progress.Root>
)
```

### Label

Add a label to provide additional context for the progress indicator.

```tsx
import { Progress } from '@ark-ui/react/progress'
import styles from 'styles/progress-circular.module.css'

export const WithLabel = () => (
  <Progress.Root className={styles.Root} defaultValue={42}>
    <Progress.Label className={styles.Label}>Label</Progress.Label>
    <div className={styles.CircleContainer}>
      <Progress.Circle className={styles.Circle}>
        <Progress.CircleTrack className={styles.CircleTrack} />
        <Progress.CircleRange className={styles.CircleRange} />
      </Progress.Circle>
      <Progress.ValueText className={styles.ValueText} />
    </div>
  </Progress.Root>
)
```

### Root Provider

An alternative way to control the progress is to use the `RootProvider` component and the `useProgress` hook. This way
you can access the state and methods from outside the component.

```tsx
import { Progress, useProgress } from '@ark-ui/react/progress'
import button from 'styles/button.module.css'
import styles from 'styles/progress-circular.module.css'

export const RootProvider = () => {
  const progress = useProgress()

  return (
    <div className="stack">
      <button className={button.Root} onClick={() => progress.setToMax()}>
        Set to Max
      </button>
      <Progress.RootProvider className={styles.Root} value={progress}>
        <div className={styles.CircleContainer}>
          <Progress.Circle className={styles.Circle}>
            <Progress.CircleTrack className={styles.CircleTrack} />
            <Progress.CircleRange className={styles.CircleRange} />
          </Progress.Circle>
          <Progress.ValueText className={styles.ValueText} />
        </div>
      </Progress.RootProvider>
    </div>
  )
}
```

## Guides

### Styling the Circle

The circular progress component uses CSS variables to control the size and thickness of the circle. Set these variables
on `Progress.Circle` to customize the appearance:

```css
[data-scope='progress'][data-part='circle'] {
  --size: 120px;
  --thickness: 10px;
}
```

| Variable      | Description                          |
| ------------- | ------------------------------------ |
| `--size`      | The width and height of the circle   |
| `--thickness` | The stroke width of the circle track |

## API Reference

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`defaultValue`**
Type: `number`
Required: false
Default Value: `50`
Description: The initial value of the progress bar when rendered.
Use when you don't need to control the value of the progress bar.

**`formatOptions`**
Type: `NumberFormatOptions`
Required: false
Default Value: `{ style: "percent" }`
Description: The options to use for formatting the value.

**`id`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The unique identifier of the machine.

**`ids`**
Type: `Partial<{ root: string; track: string; label: string; circle: string }>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the progress bar. Useful for composition.

**`locale`**
Type: `string`
Required: false
Default Value: `"en-US"`
Description: The locale to use for formatting the value.

**`max`**
Type: `number`
Required: false
Default Value: `100`
Description: The maximum allowed value of the progress bar.

**`min`**
Type: `number`
Required: false
Default Value: `0`
Description: The minimum allowed value of the progress bar.

**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Callback fired when the value changes.

**`orientation`**
Type: `'horizontal' | 'vertical'`
Required: false
Default Value: `"horizontal"`
Description: The orientation of the element.

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: The localized messages to use.

**`value`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The controlled value of the progress bar.

#### Data Attributes

**`data-scope`**: progress
**`data-part`**: root
**`data-max`**: 
**`data-value`**: The value of the item
**`data-state`**: 
**`data-orientation`**: The orientation of the progress

### Circle

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### CircleRange

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: progress
**`data-part`**: circle-range
**`data-state`**: 

### CircleTrack

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: progress
**`data-part`**: circle-track
**`data-orientation`**: The orientation of the circletrack

### Label

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: progress
**`data-part`**: label
**`data-orientation`**: The orientation of the label

### Range

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: progress
**`data-part`**: range
**`data-orientation`**: The orientation of the range
**`data-state`**: 

### RootProvider

#### Props

**`value`**
Type: `UseProgressReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Track

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### ValueText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### View

#### Props

**`state`**
Type: `ProgressState`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: progress
**`data-part`**: view
**`data-state`**: 

## Accessibility

Complies with the [the progressbar role requirements.](https://w3c.github.io/aria/#progressbar).