Circular Progress

Circular progress indicators are utilized to indicate an undetermined wait period or visually represent the duration of a process.


Installation

npx nextui-cli@latest add progress
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

Usage

Note: Make sure to pass the aria-label prop when the label prop is not provided. This is required for accessibility.

Sizes

Colors

With Label

With Value

Value Formatting

Values are formatted as a percentage by default, but this can be modified by using the formatOptions prop to specify a different format. formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

Slots

  • base: The base slot of the circular progress, it is the main container.
  • svgWrapper: The wrapper of the svg circles and the value label.
  • svg: The svg element of the circles.
  • track: The track is the background circle of the circular progress.
  • indicator: The indicator is the one that is filled according to the value.
  • value: The value content.
  • label: The label content.

Custom Styles

You can customize the CircularProgress component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

CircularProgress has the following attributes on the base element:

  • data-indeterminate: Indicates whether the progress is indeterminate.
  • data-disabled: Indicates whether the progress is disabled. Based on isDisabled prop.

Accessibility

  • Exposed to assistive technology as a progress bar via ARIA.
  • Labeling support for accessibility.
  • Internationalized number formatting as a percentage or value.
  • Determinate and indeterminate progress support.
  • Exposes the aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext attributes.

API

Circular Progress Props

AttributeTypeDescriptionDefault
labelReactNodeThe content to display as the label.-
sizesm | md | lgThe size of the indicator.md
colordefault | primary | secondary | success | warning | dangerThe color of the indicator.primary
valuenumberThe current value (controlled).-
valueLabelReactNodeThe content to display as the value's label (e.g. 1 of 4).-
minValuenumberThe smallest value allowed for the input.0
maxValuenumberThe largest value allowed for the input.100
formatOptionsIntl.NumberFormatThe options to format the value.{style: 'percent'}
isIndeterminatebooleanWhether the progress is indeterminate.true
showValueLabelbooleanWhether to show the value label.true
strokeWidthnumberThe width of the progress stroke.2
isDisabledbooleanWhether the progress is disabled.false
disableAnimationbooleanWhether to disable the animation.false
classNamesRecord<"base"|"svgWrapper"|"svg"|"track"|"indicator"|"value"|"label", string>Allows to set custom class names for the circular progress slots.-