mirror of
https://github.com/nextui-org/nextui.git
synced 2025-12-08 19:26:11 +00:00
124 lines
6.7 KiB
Plaintext
124 lines
6.7 KiB
Plaintext
---
|
||
title: "Circular Progress"
|
||
description: "Circular progress indicators are utilized to indicate an undetermined wait period or visually represent the duration of a process."
|
||
---
|
||
|
||
import {circularProgressContent} from "@/content/components/circular-progress";
|
||
|
||
# Circular Progress
|
||
|
||
Circular progress indicators are utilized to indicate an undetermined wait period or visually represent the duration of a process.
|
||
|
||
<ComponentLinks component="progress" styles="circular-progress" storybook="circularprogress" reactAriaHook="useProgressBar" />
|
||
|
||
---
|
||
|
||
<CarbonAd/>
|
||
|
||
## Import
|
||
|
||
<ImportTabs
|
||
commands={{
|
||
main: 'import {CircularProgress} from "@nextui-org/react";',
|
||
individual: 'import {CircularProgress} from "@nextui-org/progress";',
|
||
}}
|
||
/>
|
||
|
||
## Usage
|
||
|
||
<CodeDemo title="Usage" files={circularProgressContent.usage} />
|
||
|
||
> **Note**: Make sure to pass the `aria-label` prop when the `label` prop is not provided. This is required for accessibility.
|
||
|
||
### Sizes
|
||
|
||
<CodeDemo title="Sizes" files={circularProgressContent.sizes} />
|
||
|
||
### Colors
|
||
|
||
<CodeDemo title="Colors" files={circularProgressContent.colors} />
|
||
|
||
### With Label
|
||
|
||
<CodeDemo title="With Label" files={circularProgressContent.label} />
|
||
|
||
### With Value
|
||
|
||
<CodeDemo title="With Value" files={circularProgressContent.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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) and is applied based on the current locale.
|
||
|
||
<CodeDemo
|
||
title="Value Formatting"
|
||
files={circularProgressContent.valueFormatting}
|
||
highlightedLines="10"
|
||
/>
|
||
|
||
## 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.
|
||
|
||
<CodeDemo
|
||
title="Custom Styles"
|
||
files={circularProgressContent.customStyles}
|
||
highlightedLines="9-12"
|
||
/>
|
||
|
||
<Spacer y={4} />{" "}
|
||
|
||
## Data Attributes
|
||
|
||
`CircularProgress` has the following attributes on the `root` element:
|
||
|
||
- **data-indeterminate**:
|
||
Indicates whether the progress is indeterminate.
|
||
- **data-disabled**:
|
||
Indicates whether the progress is disabled. Based on `isDisabled` prop.
|
||
|
||
<Spacer y={4} />{" "}
|
||
|
||
## 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.
|
||
|
||
<Spacer y={4} />{" "}
|
||
|
||
## API
|
||
|
||
### Circular Progress Props
|
||
|
||
| Attribute | Type | Description | Default |
|
||
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------- |
|
||
| label | `ReactNode` | The content to display as the label. | - |
|
||
| size | `sm` \| `md` \| `lg` | The size of the indicator. | `md` |
|
||
| color | `default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger` | The color of the indicator. | `primary` |
|
||
| value | `number` | The current value (controlled). | - |
|
||
| valueLabel | `ReactNode` | The content to display as the value's label (e.g. 1 of 4). | - |
|
||
| minValue | `number` | The smallest value allowed for the input. | `0` |
|
||
| maxValue | `number` | The largest value allowed for the input. | `100` |
|
||
| formatOptions | [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) | The options to format the value. | `{style: 'percent'}` |
|
||
| isIndeterminate | `boolean` | Whether the progress is indeterminate. | `true` |
|
||
| showValueLabel | `boolean` | Whether to show the value label. | `true` |
|
||
| strokeWidth | `number` | The width of the progress stroke. | `2` |
|
||
| isDisabled | `boolean` | Whether the progress is disabled. | `false` |
|
||
| disableAnimation | `boolean` | Whether to disable the animation. | `false` |
|
||
| classNames | `Record<"base"｜"svgWrapper"｜"svg"｜"track"｜"indicator"｜"value"｜"label", string>` | Allows to set custom class names for the circular progress slots. | - |
|