Skip to main content

Circular Progress

Used to display the progress status for a task that takes a long time or consists of several steps within a page.

Circular Progress should not be used for initial page loading. Check out the Page Loading design pattern for more information.

Import

import { CircularProgress } from '@pluralsight/react'

Anatomy

  1. Container
  2. SVG Box
  3. Base Circle
  4. Now Cirlce
  5. Label

Usage

Basic Circular Progress

function CircularProgressExample() {
  return <CircularProgress ariaLabel="fifty percent" now={50} />
}

Indeterminate (loading) State

When you need to show the user that content within a page (that has already been loaded) is updating, use the indeterminate state. To do this, set the kind prop to indeterminate.

function IndeterminateCircularProgressExample() {
  return (
    <CircularProgress ariaLabel="Loading new courses" kind="indeterminate" />
  )
}

Sizes

The default size of the Circular Progress is m. This size should be used in most, if not all cases. The xs size should only be used when the default size is too large.

function SizesCircularProgressExample() {
  return (
    <Grid cols="repeat(12, 1fr)" gap={8} data-site-override="alignGridCenter">
      <GridItem>
        <CircularProgress ariaLabel="Xtra small progress" now={25} size="xs" />
      </GridItem>

      <GridItem>
        <CircularProgress ariaLabel="Medium progress" now={50} size="m" />
      </GridItem>
    </Grid>
  )
}

Customizing

There are 3 ways to customize the CircularProgress component.

1. Unused Classes

Each component layer of the CircularProgress has a unused class name that can be utilized in your local CSS to customize the CircularProgress at any level.

  1. pando-circular-progress: The container element of the Progress.
  2. pando-circular-progress-box: The SVG element that contains the Progress.
  3. pando-circular-progress-base: The base circle of the Progress.
  4. pando-circular-progress-now: The now circle of the Progress.

2. Passing a className prop

You can pass a className prop to the CircularProgress component to customize the CircularProgress wrapper div element. This is useful if your project uses CSS Modules or a CSS-in-JS library like Emotion.

import customStyles from './customStyles.module.css'

function CustomCircularProgress(props) {
  return (
    <CircularProgress
      className={customStyles.customProgressWrapper}
      ariaLabel="50%"
      now={50}
    />
  )
}

3. Ejected CircularProgress

For a low-level "ejected" approach, you can use the Headless-styles API to customize the CircularProgress however you prefer while keeping the accessibility behavior.

import { getCircularProgressProps } from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Loading

Do use Circular Progress to display an update of information to a specific part of a previously loaded page.

Don't use the Circular Progress to show page load progress. Instead, use a Skeleton.

Text

Do use text describing the progress in close proximity.

Don't use text or other elements within the Circular Progress.

Sizing

Do use the default size for all use cases where possible of the Circular Progress.

Don't use the "xs" size unless it is a last resort.

API

Parameters

interface CircularProgressOptions extends HTMLAttributes<HTMLDivElement> {
  ariaLabel: string
  displayLabel?: boolean
  kind?: 'determinate' | 'indeterminate'
  max?: number
  min?: number
  now?: number
  size?: 'xs' | 'm'
}
  1. Any props that are allowed on the div element.
  2. ariaLabel - A string that describes the progress to screen readers.
  3. displayLabel - A boolean that determines whether or not to display the progress percentage.
  4. kind - A string that determines whether the progress is determinate or indeterminate.
  5. max - A number that determines the maximum value of the progress. The default value is 100.
  6. min - A number that determines the minimum value of the progress. The default value is 0.
  7. now - A number that determines the current value of the progress. The default value is 0.
  8. size - A string that determines the size of the progress. The default value is 'm'.

Size Mapping

{
  xs: 'Should only be used when the default size (M) is too large.',
  m: 'Should be used in most, if not all cases.'
}

Accessibility

The Pando CircularProgress is fully accessible and screen-readable through the following features:

  1. The ariaLabel prop is required and is used to describe the progress to screen readers.
  2. The aria-valuenow attribute is used to describe the current value of the progress to screen readers.
  3. The aria-valuemin attribute is used to describe the minimum value of the progress to screen readers.
  4. The aria-valuemax attribute is used to describe the maximum value of the progress to screen readers.
  5. The role attribute is set to progressbar to describe the type of progress to screen readers.