Progress - Circular

An element that shows either determinate or indeterminate progress.

0%0%

Anatomy

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

Examples

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:

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.

Label

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

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.

API Reference

Root

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`defaultValue`	`50`	`number` The initial value of the progress bar when rendered. Use when you don't need to control the value of the progress bar.
`formatOptions`	`{ style: 'percent' }`	`NumberFormatOptions` The options to use for formatting the value.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; track: string; label: string; circle: string }>` The ids of the elements in the progress bar. Useful for composition.
`locale`	`'en-US'`	`string` The locale to use for formatting the value.
`max`	`100`	`number` The maximum allowed value of the progress bar.
`min`	`0`	`number` The minimum allowed value of the progress bar.
`onValueChange`		`(details: ValueChangeDetails) => void` Callback fired when the value changes.
`orientation`	`'horizontal'`	`'horizontal' \| 'vertical'` The orientation of the element.
`translations`		`IntlTranslations` The localized messages to use.
`value`		`number` The controlled value of the progress bar.

Attribute	Description
`[data-scope]`	progress
`[data-part]`	root
`[data-max]`
`[data-value]`	The value of the item
`[data-state]`
`[data-orientation]`	The orientation of the progress

CSS Variable	Description
`--percent`	The percent value for the root
`--radius`	The border radius value
`--circumference`	The circumference value for the root
`--offset`	The offset position of the element

Circle

Renders a <svg> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

CircleRange

Renders a <svgcircle> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	progress
`[data-part]`	circle-range
`[data-state]`

CircleTrack

Renders a <svgcircle> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	progress
`[data-part]`	circle-track
`[data-orientation]`	The orientation of the circletrack

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	progress
`[data-part]`	label
`[data-orientation]`	The orientation of the label

Range

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	progress
`[data-part]`	range
`[data-orientation]`	The orientation of the range
`[data-state]`

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseProgressReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Track

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ValueText

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

View

Renders a <span> element.

Prop	Default	Type
`state`		`ProgressState`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	progress
`[data-part]`	view
`[data-state]`

Accessibility

Complies with the the progressbar role requirements..