005cf56baf
Some checks failed
No response / noResponse (push) Has been cancelled
CI / Continuous releases (push) Has been cancelled
CI / test-dev (macos-latest) (push) Has been cancelled
CI / test-dev (ubuntu-latest) (push) Has been cancelled
CI / test-dev (windows-latest) (push) Has been cancelled
Maintenance / main (push) Has been cancelled
Scorecards supply-chain security / Scorecards analysis (push) Has been cancelled
CodeQL / Analyze (push) Has been cancelled
133 lines
4.8 KiB
Markdown
133 lines
4.8 KiB
Markdown
---
|
||
productId: joy-ui
|
||
title: React Circular Progress component
|
||
components: CircularProgress
|
||
githubLabel: 'component: CircularProgress'
|
||
---
|
||
|
||
# Circular Progress
|
||
|
||
<p class="description">The Circular Progress component showcases the duration of a process or an indefinite wait period.</p>
|
||
|
||
{{"component": "@mui/docs/ComponentLinkHeader"}}
|
||
|
||
## Introduction
|
||
|
||
A circular progress indicator, often referred to as a spinner, is a visual representation of the progress of an operation or task.
|
||
|
||
The Circular Progress component defaults to indeterminate, signifying an undefined wait duration.
|
||
Use [determinate](#determinate) mode to indicate how long a given operation will take.
|
||
|
||
{{"demo": "CircularProgressUsage.js", "hideToolbar": true, "bg": "gradient"}}
|
||
|
||
:::info
|
||
The component's animations rely primarily on CSS to ensure that it functions even before JavaScript loads.
|
||
:::
|
||
|
||
## Basics
|
||
|
||
```jsx
|
||
import CircularProgress from '@mui/joy/CircularProgress';
|
||
```
|
||
|
||
The Circular Progress component provides users with updates on the status of ongoing processes such as loading an app, submitting a form, or saving updates.
|
||
|
||
## Customization
|
||
|
||
### Variants
|
||
|
||
The Circular Progress component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid` (default), `soft`, `outlined`, and `plain`.
|
||
|
||
{{"demo": "CircularProgressVariants.js"}}
|
||
|
||
### Sizes
|
||
|
||
Circular Progress comes in three sizes: `sm`, `md` (default), and `lg`.
|
||
|
||
{{"demo": "CircularProgressSizes.js"}}
|
||
|
||
:::info
|
||
To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
|
||
:::
|
||
|
||
### Colors
|
||
|
||
Every palette included in the theme is available via the `color` prop.
|
||
|
||
{{"demo": "CircularProgressColors.js"}}
|
||
|
||
### Thickness
|
||
|
||
You can use the `thickness` prop to control the circle's stroke width.
|
||
|
||
{{"demo": "CircularProgressThickness.js"}}
|
||
|
||
### Determinate
|
||
|
||
The `determinate` prop lets you indicate a specified wait time.
|
||
|
||
{{"demo": "CircularProgressDeterminate.js"}}
|
||
|
||
### Children
|
||
|
||
By default, any children nested inside the Circular Progress will be centered.
|
||
|
||
{{"demo": "CircularProgressChildren.js"}}
|
||
|
||
:::info
|
||
For plain texts and icons, the dimension is relative to the circular progress's CSS variable (`--CircularProgress-size`).
|
||
:::
|
||
|
||
### With a button
|
||
|
||
The Circular Progress component can be used as a decorator to show loading on a button.
|
||
|
||
The size of the Circular Progress is controlled by a button, an icon button, or a link unless the `size` prop is explicitly specified on the progress.
|
||
|
||
{{"demo": "CircularProgressButton.js"}}
|
||
|
||
## Third-party integrations
|
||
|
||
### use-count-up
|
||
|
||
Use the `useCountUp` hook from the [use-count-up](https://www.npmjs.com/package/use-count-up) package to create a counting animation by providing `start`, `end`, and `duration` values.
|
||
|
||
{{"demo": "CircularProgressCountUp.js"}}
|
||
|
||
## CSS variables playground
|
||
|
||
Play around with all the CSS variables available on the component to see how the design changes.
|
||
You can use these to customize the component with both the `sx` prop and the theme.
|
||
|
||
{{"demo": "CircularProgressVariables.js", "hideToolbar": true, "bg": "gradient"}}
|
||
|
||
## Accessibility
|
||
|
||
Out of the box, the `aria-valuenow` attribute will indicate the current value of the progress bar only when the value is not indeterminate.
|
||
This attribute will display the value as a percentage.
|
||
|
||
Here are a few tips to make sure you have an accessible circular progress component:
|
||
|
||
- When creating your circular progress component, ensure sufficient color contrast between it and the background, using a minimum of [WCAG 2.0's color contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) of 4.5:1.
|
||
- To define a human-readable text alternative to `aria-valuenow`, the `aria-valuetext` will show the current value in a more user-friendly way.
|
||
For example, downloading files might be conveyed as `aria-valuetext="8% (34 minutes) remaining`.
|
||
- The `aria-valuemin` and `aria-valuemax` attributes are commonly used to indicate the minimum and maximum values of a range.
|
||
By default, these attributes are set to 0 and 100, respectively.
|
||
If you need to set a different minimum or maximum value for your range, you can use the these attributes to do so.
|
||
- Use the `aria-label` or `aria-labelledby` attribute to provide an accessible name for your progress component.
|
||
These define the string value or identifies the element(s) that label the progress component.
|
||
|
||
## Anatomy
|
||
|
||
The Circular Progress component is composed of a single root `<span>` with an `<svg>` component that wraps around two `<circle>`.
|
||
|
||
```html
|
||
<span role="progressbar" class="MuiCircularProgress-root">
|
||
<svg class="MuiCircularProgress-svg">
|
||
<circle class="MuiCircularProgress-track"></circle>
|
||
<circle class="MuiCircularProgress-progress"></circle>
|
||
</svg>
|
||
<!-- children are nested here when present -->
|
||
</span>
|
||
```
|