Skip to main content

Progress Bar

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

Import

import { ProgressBar } from '@pluralsight/react'

Anatomy

  1. Container
  2. Bar

Usage

Basic Progress

function BasicProgressBar() {
  return (
    <div>
      <ProgressBar ariaLabel="25%" now={25} kind="inset" />
      <br />
      <ProgressBar ariaLabel="50%" now={50} kind="linear" />
    </div>
  )
}

Sizes

function ProgressSizes() {
  return (
    <div>
      <ProgressBar ariaLabel="xtra small progress bar" now={50} size="xs" />
      <br />
      <ProgressBar ariaLabel="small progress bar" now={75} size="s" />
    </div>
  )
}

Customizing

There are 3 ways to customize the ProgressBar component.

1. Unused Classes

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

  1. pando-progress: The container element of the Progress Bar.
  2. pando-progress-bar: The "now" element of the Progress Bar.

2. Passing a className prop

You can pass a className prop to the ProgressBar component to customize the ProgressBar 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 CustomProgressBar(props) {
  return (
    <ProgressBar
      className={customStyles.customProgressWrapper}
      ariaLabel="50%"
      now={50}
    />
  )
}

3. Ejected ProgressBar

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

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

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

Behavior

Loading

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

Don't use the 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 Progress.

Sizing

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

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

API

Parameters

interface ProgressProps extends HTMLAttributes<HTMLDivElement> {
  ariaLabel: string
  kind?: 'linear' | 'inset'
  max?: number
  min?: number
  now?: number
  size?: 'xs' | 's'
}
  1. Any props that can be passed to a 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 's'.

Size Mapping

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

Accessibility

The Pando ProgressBar 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.