--- 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