Skip to content
Edit this page
+

Circular Progress

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

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.

<CircularProgress />

Playground

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.

Press Enter to start editing

Sizes

Circular Progress comes in three sizes: sm, md (default), and lg.

Press Enter to start editing

Colors

Every palette included in the theme is available via the color prop.

Variant:

Thickness

You can use the thickness prop to control the circle's stroke width.

Determinate

The determinate prop lets you indicate a specified wait time.

Press Enter to start editing

Children

By default, any children nested inside the Circular Progress will be centered.

2 / 3
Press Enter to start editing

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.

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

<CircularProgress />

CSS Variables

px

Supports only `px` unit

px

px

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>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.