Progress Steps

Version 2.1.1Github Storybook

Progress Steps can be a presentational or interactive component and shows users an outline of a complex multi-step task.

const ProgressStepsExample = () => {
  return (
    <ProgressSteps>
      <ProgressStepComplete as="button" onClick={() => {}}>Sign up</ProgressStepComplete>
      <ProgressStepSeparator />
      <ProgressStepError as="button" onClick={() => {}}>Validate email</ProgressStepError>
      <ProgressStepSeparator />
      <ProgressStepCurrent as="button" onClick={() => {}}>Complete profile</ProgressStepCurrent>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="button" onClick={() => {}}>Add friends</ProgressStepIncomplete>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="button" onClick={() => {}} disabled>
        Start event
      </ProgressStepIncomplete>
    </ProgressSteps>
  );
};

render(<ProgressStepsExample />);

Guidelines

About Progress Steps

Progress Steps are a visual representation of a complex task broken up into multiple steps, ideally 3–5. They indicate what has and what needs to be done to fully complete the task. Use Progress Steps to show a clear path to completion, especially when the task is nonlinear or can’t be completed in one sitting.

Not all multi-step tasks need Progress Steps. Tasks that are short, straightforward, and linear probably don’t need the extra layer of information that Progress Steps provides.

Each step can communicate one of these statuses:

Complete: The user has completed this step with no more action needed.
Incomplete: The user has interacted with this step but there is still more action needed.
Current: The user is currently on this step.
Error: The user has interacted with this step but more action is required that will prevent completing the full task.
Incomplete + Disabled: This step is not yet reached by a user.

Ordered Display List vs Progress Steps

Progress Steps

Progress Steps show users an outline of a complex multi-step task across multiple pages.
Progress Steps convey progression and have interactive status states.

Ordered Display List

Ordered Display Lists structure tasks but don’t outline or show progression or status through a multi-step task.
Ordered Display Lists organize complex tasks within a single screen, especially in flows where users need to complete tasks outside of Twilio.

Accessibility

Give each step a concise label describing what the goal of that step is.
Each step icon has a title prop whose value is the current status of that step (e.g. complete, incomplete, etc.) to inform screen readers of a step's status. This label is adjustable for internationalization.
The ProgressStep has role=list and each step has role=listitem for screen readers.
The ProgressStep has aria-current set to step for the current step.

Examples

Progress Steps as buttons

Use Progress Steps as buttons when each step triggers an in-page action and doesn’t have a unique URL. We recommend using this button action to save information in each step.

Only button steps may be disabled.

const ProgressStepsExample = () => {
  return (
    <ProgressSteps>
      <ProgressStepComplete as="button" onClick={() => {}}>Sign up</ProgressStepComplete>
      <ProgressStepSeparator />
      <ProgressStepError as="button" onClick={() => {}}>Validate email</ProgressStepError>
      <ProgressStepSeparator />
      <ProgressStepCurrent as="button" onClick={() => {}}>Complete profile</ProgressStepCurrent>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="button" onClick={() => {}}>Add friends</ProgressStepIncomplete>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="button" onClick={() => {}} disabled>
        Start event
      </ProgressStepIncomplete>
    </ProgressSteps>
  );
};

render(<ProgressStepsExample />);

Progress Steps as anchors

Use Progress Steps as anchors when each step links to other pages and has a unique URL.

const ProgressStepsExample = () => {
  return (
    <ProgressSteps>
      <ProgressStepComplete as="a" href="#">Sign up</ProgressStepComplete>
      <ProgressStepSeparator />
      <ProgressStepError as="a" href="#">Validate email</ProgressStepError>
      <ProgressStepSeparator />
      <ProgressStepCurrent as="a" href="#">Complete profile</ProgressStepCurrent>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="a" href="#">Add friends</ProgressStepIncomplete>
    </ProgressSteps>
  );
};

render(<ProgressStepsExample />);

Non-interactive Progress Steps

Use Progress Steps as divs when steps have no need for user interaction.

const ProgressStepsExample = () => {
  return (
    <ProgressSteps>
      <ProgressStepComplete as="div">Sign up</ProgressStepComplete>
      <ProgressStepSeparator />
      <ProgressStepError as="div">Validate email</ProgressStepError>
      <ProgressStepSeparator />
      <ProgressStepCurrent as="div">Complete profile</ProgressStepCurrent>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="div">Add friends</ProgressStepIncomplete>
    </ProgressSteps>
  );
};

render(<ProgressStepsExample />);

Progress Steps represented vertically

Use vertical Progress Steps when you’re constrained on vertical space in your layout.

const ProgressStepsExample = () => {
  return (
    <ProgressSteps orientation="vertical">
      <ProgressStepComplete as="div">Sign up</ProgressStepComplete>
      <ProgressStepSeparator />
      <ProgressStepError as="div">Validate email</ProgressStepError>
      <ProgressStepSeparator />
      <ProgressStepCurrent as="div">Complete profile</ProgressStepCurrent>
      <ProgressStepSeparator />
      <ProgressStepIncomplete as="div">Add friends</ProgressStepIncomplete>
    </ProgressSteps>
  );
};

render(<ProgressStepsExample />);

Internationalization

Each step within the Progress Step component has a label which can be set to adjust the icon's title for internationalization.

const ProgressStepsExample = () => {
  return (
    <ProgressSteps>
      <ProgressStepComplete i18nCompleteLabel="Complété" as="div">S'inscrire</ProgressStepComplete>
      <ProgressStepSeparator />
      <ProgressStepError i18nErrorLabel="Erreur" as="div">Email validé</ProgressStepError>
      <ProgressStepSeparator />
      <ProgressStepCurrent i18nCurrentLabel="Actuelle" as="div">Complétez votre profil</ProgressStepCurrent>
      <ProgressStepSeparator />
      <ProgressStepIncomplete i18nIncompleteLabel="Incomplet" as="div">Ajouter des amis</ProgressStepIncomplete>
    </ProgressSteps>
  );
};

render(<ProgressStepsExample />);

Composition Notes

Each step must have a label. Keep the label concise with fewer than 5 words per label.
Skip articles like “a” or “the” to shorten the step.
Generally, start each step with a verb to keep the user grounded in the task at hand.
If the process has 5 steps and describing each one with a verb + noun is too long, consider shortening the step labels to just a verb, and using the in-page step label to clarify the full scope of the task. For example, use “Add” as a step label, but include “Add entry step” as the page label.
If the process does not fit into a mental model of performing tasks, make sure each step is phrased consistently. For example, “Business profile” and “Brand registration.”
Keep the placement of Progress Steps consistent between different pages (steps).

When to use an error step

Show the error status on a step when it’s not the current step they’re on. When a user navigates to the step that has errors, use ProgressStepCurrent to set the status of the step to current, and use in-page validation to then communicate the errors in the current page. Check out the Error state pattern for more guidance.

Do and don't

Create profile

Do

Use Progress Steps for complex tasks with 3–5 steps that can't be completed in one session.

Name

Password

Don't

Don’t use Progress Steps for every single kind of task that has multiple steps. A line of text can be used as an alternative to show progression (e.g., “Step 1 of 2”)

Create profile

Do

Make the labels of each step short, descriptive, and consistent. Use fewer than 5 words for each step label.

Business profile for your primary business account

A2P brand

Finalize campaign registration

Don't

Don’t use long or inconsistent labels with mismatched parts of speech.

Do

Keep Progress Steps in a consistent location between steps or pages.

Don't

Don’t change the placement of Progress Steps between steps or pages.

Do

Include only one Progress Steps component per task or page.

Don't

Don’t embed a Progress Steps component within a task that’s already being tracked with another Progress Steps component. Don’t use multiple Progress Steps per page.