mirror of
https://github.com/nextui-org/nextui.git
synced 2025-12-08 19:26:11 +00:00
baec55029d
* chore(root): menu and select components in progress * chore(root): merged with main * feat(menu): stories created * feat(dropdown): menu migrated to menu component * feat(select): base implementation in progress * feat(select): listbox implemented * feat(select): scroll overflow and auto scroll added * feat(select): colors & variants improved, inside placement complete, outside pending * feat(scroll-shadow): new component in progress * feat(select): scroll shadow integrated * fix(select): popover implementation, more scroll shadow stories added * feat(listbox): custom styles example added to stories * chore(listbox): overflow hidden removed * feat(select): variants and styles completed * chore(select): description story added * feat(select): more stories added * fix(select): dynamic collections inference, styles improved, more stories added * fix(select): auto scroll to selected item, scroll padding added * chore(select): scroll behavior changed to nearest * feat(select): custom item story added * fix(select): autoscroll fixed * feat(select): multi select support added * feat(select): more examples added, clean-package modified to remove dev packages * chore(modal): useImperativeHandle removed * feat(select): render value story improved * feat(docs): listbox & scroll shadow docs done * feat(docs): select documentation in progress * fix: select aria label (#1425) * feat(docs): more examples added * feat(docs): select multiple added, storybook favicon changed * fix: added value to aria label of select (#1431) * feat(select): more examples added, storybook favicon changed * fix(popover): dialog role removed * feat(select): api added, async loading exampled added * fix: fixed list box on click not working with sr click (#1439) * feat(select): async items loading support added and documented * feat(root): input styles updated to be as the select ones * chore(root): listbox and scroll shadow readme updated * feat(select): ts examples added, banner updated * fix(popover): voiceover closes when focusing an item fixed * chore(select): focus scope removed * fix(popover): free solo popover added to use without a trigger * feat(select): blog post added * chore(docs): search meta generated, multi controlled onchange example fixed * chore(root): changeset added --------- Co-authored-by: Jakob Guddas <github@jguddas.de>
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 `base` 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. | - |
|