ProgressBar

Status: Stable

Progress bars visualize the expected time for a user to complete a process. They help the user anticipate how much time is needed to reach an end state. Progress bars should be visible, readable, and accurately reflect the progress made towards an end state.

Track: Illustrates the length of the process.
Indicator: Forward and backward movement to show where the user is in the process versus what they’ve completed.
Value label: Numeric values to describe the number of steps total, remaining, and completed.
Label (optional): Describes a specific step or summarizes the overall process to orient users. Label should be a max of 35 characters.

Examples

Step

The value label should reflect the type of steps (e.g. "Step X of Y" or "Section X of Y").
If a label is specified, it is separated from the value label with a colon (e.g. "Step X of X: Title").

Step 1 of 3: Getting started

Open in Playroom

() => {
  const [step, setStep] = React.useState(1);
  const next = () => setStep(curr => Math.min(curr + 1, 3));
  const previous = () => setStep(curr => Math.max(curr - 1, 1));
  const label = [
    "Getting started",
    "Personal information",
    "Submit your application"
  ][step - 1];

  return (
    <Stack>
      <ProgressBar variant="step" max={3} value={step} label={label} />
      <Cluster align="right">
        <Button tertiary onClick={previous}>Previous</Button>
        <Button primary onClick={next}>Next</Button>
      </Cluster>
    </Stack>
  );
};

Percentage

The value label will show a percentage from 0-100%.
If a label is specified, it is separated from the value label with a dot ("•") (e.g. "Home information • 20% completed").

Phase 1 • 25% completed

Open in Playroom

() => {
  const [step, setStep] = React.useState(1);
  const next = () => setStep(curr => Math.min(curr + 1, 4));
  const previous = () => setStep(curr => Math.max(curr - 1, 1));
  const label = `Phase ${step}`;

  return (
    <Stack>
      <ProgressBar variant="percentage" max={4} value={step} label={label} />
      <Cluster align="right">
        <Button tertiary onClick={previous}>Previous</Button>
        <Button primary onClick={next}>Next</Button>
      </Cluster>
    </Stack>
  );
};

Design guidelines

Show users how long the process takes to complete

DOClearly state how much time is remaining in the process.

Help users navigate the process

DOUse an affordance that allows a user to move to a previous question, next question, or exit the process.

DON'TMove the indicator backward unless the user chose to move to the previous question.

Keep progress bars clearly visible and readable

DOPlace the progress bar at the top of the page and and in close proximity of page content.

DON'TPlace the progress bar below questions or directly above back/controls.

Development

Customizing the value label

When using the step variant of this component, you can use the stepLabel and separator props to influence how the value label is rendered.

Section 1 of 4

Step 1/4

Step 1 out of 4

<Stack>
  <ProgressBar variant="step" max={4} value={1} stepLabel="Section" />
  <ProgressBar variant="step" max={4} value={1} separator="/" />
  <ProgressBar variant="step" max={4} value={1} separator="Part" separator=" out of " />
</Stack>

<Stack>
  <ProgressBar variant="step" max={4} value={1} stepLabel="Section" />
  <ProgressBar variant="step" max={4} value={1} separator="/" />
  <ProgressBar variant="step" max={4} value={1} separator="Part" separator=" out of " />
</Stack>

Open in Playroom

<Stack>
  <ProgressBar variant="step" max={4} value={1} stepLabel="Section" />
  <ProgressBar variant="step" max={4} value={1} separator="/" />
  <ProgressBar variant="step" max={4} value={1} separator="Part" separator=" out of " />
</Stack>

Props

<ProgressBar>

className

Deprecated

string

max

number

label

string

separator

string

stepLabel

string

value

Required

number

variant

"percentage" | "step"

ref

(instance: any) => void | RefObject<any>

ProgressBar

Examples

Step

Percentage

Design guidelines

Show users how long the process takes to complete

Help users navigate the process

Keep progress bars clearly visible and readable

Development

Customizing the value label

Props

<ProgressBar>

Related pages