ProgressBar

A ProgressBar is a simple chart that can be used to show how complete something is, or visualize parts that make up a whole.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

<ProgressBar progress="33" aria-label="4 of 12 tasks completed" />

<ProgressBar progress="33" aria-label="4 of 12 tasks completed" />

Default to pairing the ProgressBar with text that explicitly shows the value(s) of the filled segment(s). Text values are not explicitly required, but should only be omitted when the progress is intentionally vague.

Accessibility guidelines

4 of 12

tasks completed

<>
  <ProgressBar progress="33" aria-label="4 of 12 tasks completed" />
  <Text sx={{color: 'var(--fgColor-muted)', font: 'var(--text-body-shorthand-medium)'}}>4 of 12</Text>
  {/* this Box is visually hidden, but conveys context for screen readers */}
  <Box
    sx={{
      '&:not(:focus):not(:active):not(:focus-within)': {
        clipPath: 'inset(50%)',
        height: '1px',
        overflow: 'hidden',
        position: 'absolute',
        whiteSpace: 'nowrap',
        width: '1px',
      },
    }}
  >
    tasks completed
  </Box>
</>

<>
  <ProgressBar progress="33" aria-label="4 of 12 tasks completed" />
  <Text sx={{color: 'var(--fgColor-muted)', font: 'var(--text-body-shorthand-medium)'}}>4 of 12</Text>
  {/* this Box is visually hidden, but conveys context for screen readers */}
  <Box
    sx={{
      '&:not(:focus):not(:active):not(:focus-within)': {
        clipPath: 'inset(50%)',
        height: '1px',
        overflow: 'hidden',
        position: 'absolute',
        whiteSpace: 'nowrap',
        width: '1px',
      },
    }}
  >
    tasks completed
  </Box>
</>

Multiple segments

A ProgressBar may use segments to represent multiple parts of a whole.

When using multiple segments:

Use colors that are easy to tell apart and include a legend that identifies what each segment represents.
Avoid overwhelming users by with too many segments. This is especially important for narrow ProgressBars. Consider a different kind of chart for these cases.

Done

In progress

Closed

<>
  <ProgressBar aria-valuenow={50}>
    <ProgressBar.Item progress={30} sx={{bg: 'success.emphasis'}} aria-label="30%" />
    <ProgressBar.Item progress={15} sx={{bg: 'accent.emphasis'}} aria-label="15%" />
    <ProgressBar.Item progress={5} sx={{bg: 'danger.emphasis'}} aria-label="5%" />
  </ProgressBar>
  <Stack direction="horizontal" wrap="wrap" role="presentation">
    <Stack direction="horizontal" gap="condensed" align="center">
      <DotFillIcon fill="var(--bgColor-success-emphasis)" />
      Done
    </Stack>
    <Stack direction="horizontal" gap="condensed" align="center">
      <DotFillIcon fill="var(--bgColor-accent-emphasis)" />
      In progress
    </Stack>
    <Stack direction="horizontal" gap="condensed" align="center">
      <DotFillIcon fill="var(--bgColor-danger-emphasis)" />
      Closed
    </Stack>
  </Stack>
</>

<>
  <ProgressBar aria-valuenow={50}>
    <ProgressBar.Item progress={30} sx={{bg: 'success.emphasis'}} aria-label="30%" />
    <ProgressBar.Item progress={15} sx={{bg: 'accent.emphasis'}} aria-label="15%" />
    <ProgressBar.Item progress={5} sx={{bg: 'danger.emphasis'}} aria-label="5%" />
  </ProgressBar>
  <Stack direction="horizontal" wrap="wrap" role="presentation">
    <Stack direction="horizontal" gap="condensed" align="center">
      <DotFillIcon fill="var(--bgColor-success-emphasis)" />
      Done
    </Stack>
    <Stack direction="horizontal" gap="condensed" align="center">
      <DotFillIcon fill="var(--bgColor-accent-emphasis)" />
      In progress
    </Stack>
    <Stack direction="horizontal" gap="condensed" align="center">
      <DotFillIcon fill="var(--bgColor-danger-emphasis)" />
      Closed
    </Stack>
  </Stack>
</>

Animated

<ProgressBar animated progress="33" aria-label="4 of 12 tasks completed" />

<ProgressBar animated progress="33" aria-label="4 of 12 tasks completed" />

Custom size

The size may be adjusted to adapt the ProgressBar to different contexts.

Size options:

Small
Medium (default)
Large

The following example uses the 'large' size variant.

<ProgressBar barSize="large" progress="33" aria-label="4 of 12 tasks completed" />

<ProgressBar barSize="large" progress="33" aria-label="4 of 12 tasks completed" />

Custom color

The color of the filled segments of the ProgressBar may be customized.

<ProgressBar bg="done.emphasis" progress="33" aria-label="4 of 12 tasks completed" />

<ProgressBar bg="done.emphasis" progress="33" aria-label="4 of 12 tasks completed" />

More code examples

See the ProgressBar Storybook stories.

Props

ProgressBar

Name	Required	Description
animated		`boolean` Whether the filled in area(s) of the progress bar will be animated or not
progress		`number` Used to set the size of the green bar
barSize		`\| 'small' \| 'large' \| 'default'` Controls the height of the progress bar. If omitted, height is set to the default height.
inline		`boolean` Styles the progress bar inline
bg		`string` Set the progress bar color
sx		`SystemStyleObject`

ProgressBar.Item

Name	Required	Description
aria-label		`string` Defines a string value that labels the current element. @see aria-labelledby.
bg		`string` Set the progress segment color
progress		`string \| number` Used to set the size of the green bar
sx		`SystemStyleObject`