---
title: Circular Progress
description: Using the circular progress machine in your project.
package: "@zag-js/progress"
slugAlias: "progress"
---
Circular progress is a circular progress bar that can be used to show the
progress of a task such as downloading a file, uploading an image, etc.
**Features**
- Supports minimum and maximum values
- Supports indeterminate progress bars
## Installation
Install the progress package:
## Anatomy
Check the progress anatomy and part names.
> Each part includes a `data-part` attribute to help identify them in the DOM.
## Usage
Import the progress package:
```tsx
import * as progress from "@zag-js/progress"
```
The progress package exports two key functions:
- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.
> Pass a unique `id` to `useMachine` so generated element ids stay predictable.
Then use the framework integration helpers:
### Setting the value
Use `defaultValue` for uncontrolled state, or `value` for controlled state.
```tsx {2}
const service = useMachine(progress.machine, {
defaultValue: 50,
})
```
Subsequently, you can use the `api.setValue` method to set the value of the
progress bar.
```tsx
api.setValue(50)
```
### Listening for value changes
Use `onValueChange` to react to progress updates.
```tsx
const service = useMachine(progress.machine, {
onValueChange(details) {
// details => { value: number | null }
console.log(details.value)
},
})
```
### Setting the minimum and maximum values
By default, the progress bar has a minimum value of `0` and a maximum value of
`100`. You can change these values by passing the `min` and `max` options to the
machine.
```tsx {2-3}
const service = useMachine(progress.machine, {
min: 0,
max: 1000,
})
```
### Using the indeterminate state
The progress component is determinate by default, with the value and max set to
`50` and `100` respectively.
Set `value` to `null` to indicate an indeterminate value for operations whose
progress can't be determined (e.g., attempting to reconnect to a server).
```tsx {2}
const service = useMachine(progress.machine, {
defaultValue: null,
})
```
### Customizing value text
Progress bars can only be interpreted by sighted users. To include a text
description to support assistive technologies like screen readers, use the
`valueText` part.
```tsx
const service = useMachine(progress.machine, {
translations: {
value: ({ value, max }) =>
value == null ? "Loading..." : `${value} of ${max} items loaded`,
},
})
```
### Setting the size of the progress bar
Use the `--size` CSS variable to set the size of the progress bar.
```css
[data-scope="progress"][data-part="circle"] {
--size: 400px;
}
```
### Setting the thickness of the progress bar
Use the `--thickness` CSS variable to set the size of the progress bar.
```css
[data-scope="progress"][data-part="circle"] {
--thickness: 4px;
}
```
Then you need to render the `valueText` part in your component.
```tsx
{api.valueAsString}
```
### Localizing percentage formatting
Use `locale` and `formatOptions` to customize number formatting.
```tsx
const service = useMachine(progress.machine, {
locale: "fr-FR",
formatOptions: { style: "percent", maximumFractionDigits: 1 },
})
```
## Styling guide
Each part includes a `data-part` attribute you can target in CSS.
```css
[data-scope="progress"][data-part="root"] {
/* Styles for the root part */
}
[data-scope="progress"][data-part="circle-track"] {
/* Styles for the track part */
}
[data-scope="progress"][data-part="circle-range"] {
/* Styles for the range part */
}
```
### Indeterminate state
To style the indeterminate state, you can use the `[data-state=indeterminate]`
selector.
```css
[data-scope="progress"][data-part="root"][data-state="indeterminate"] {
/* Styles for the root indeterminate state */
}
[data-scope="progress"][data-part="circle-track"][data-state="indeterminate"] {
/* Styles for the root indeterminate state */
}
[data-scope="progress"][data-part="circle-range"][data-state="indeterminate"] {
/* Styles for the root indeterminate state */
}
```
## Methods and Properties
### Machine Context
The progress machine exposes the following context properties:
### Machine API
The progress `api` exposes the following methods:
### Data Attributes