react-test/docs/data/joy/components/circular-progress/circular-progress.md

productId, title, components, githubLabel

productId	title	components	githubLabel
joy-ui	React Circular Progress component	CircularProgress	component: CircularProgress

Circular Progress

The Circular Progress component showcases the duration of a process or an indefinite wait period.

{{"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 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

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: 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. :::

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 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 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>.

<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>