Stepper usage guidelines

Caution

This component is currently in an unstable state and may undergo significant changes in future releases.

Steppers provide users with a visual guide as they work through multi-step processes and workflows.

When to use

• To show progress through a linear multi-step workflow.
• To break down complex tasks and workflows into manageable, sequential steps.
• To show users a resource’s status or progress in a process.

When not to use

• For workflows that don’t follow a specific order. Consider using tabs or other patterns instead.
• For app navigation outside of linear workflows. Consider using tabs, a sidebar, or other navigation solutions for this.

Usage

With navigation

Preview

Completed:

Step 1

This is the first step.

In progress:

Step 2

This is the second step.

Incomplete:

Step 3

This is the third step.

BackNext

Code

import { Button, Stack, UNSTABLE_Stepper as Stepper, UNSTABLE_StepperItem as StepperItem } from '@cimpress-ui/react';
import { useReducer } from 'react';

const STEPS = [
  {
    title: 'Step 1',
    description: 'This is the first step.',
  },
  {
    title: 'Step 2',
    description: 'This is the second step.',
  },
  {
    title: 'Step 3',
    description: 'This is the third step.',
  },
];

export default function Example() {
  const [currentStep, dispatch] = useReducer(
    (state: number, action: { type: 'NEXT' | 'BACK' | 'SET'; payload?: number }) => {
      switch (action.type) {
        case 'NEXT':
          return Math.min(state + 1, STEPS.length - 1);
        case 'BACK':
          return Math.max(state - 1, 0);
        case 'SET':
          return Math.max(Math.min(action.payload ?? state, STEPS.length - 1), 0);
        default:
          return state;
      }
    },
    1,
  );

  return (
    <Stack gap={16}>
      <Stepper currentStep={currentStep} onChange={(step) => dispatch({ type: 'SET', payload: step })}>
        {STEPS.map((step) => (
          <StepperItem key={step.title} description={step.description}>
            {step.title}
          </StepperItem>
        ))}
      </Stepper>
      <Stack direction="horizontal" gap={16} justify="center">
        <Button onPress={() => dispatch({ type: 'BACK' })}>Back</Button>
        <Button onPress={() => dispatch({ type: 'NEXT' })}>Next</Button>
      </Stack>
    </Stack>
  );
}

Copy code Open in playground

Steppers can be used to guide users through a linear workflow. Users can revisit or edit previous steps, but cannot skip ahead to incomplete steps.

Properties

Orientation

Preview

Incomplete:

Step 1

This is the first step

Incomplete:

Step 2

This is the current step

Incomplete:

Step 3

This is the next step

Code

import { UNSTABLE_Stepper as Stepper, UNSTABLE_StepperItem as StepperItem } from '@cimpress-ui/react';

export default function Example() {
  return (
    <Stepper>
      <StepperItem description="This is the first step">Step 1</StepperItem>
      <StepperItem description="This is the current step">Step 2</StepperItem>
      <StepperItem description="This is the next step">Step 3</StepperItem>
    </Stepper>
  );
}

Copy code Open in playground

Preview

Incomplete:

Step 1

This is the first step

Incomplete:

Step 2

This is the current step

Incomplete:

Step 3

This is the next step

Code

import { UNSTABLE_Stepper as Stepper, UNSTABLE_StepperItem as StepperItem } from '@cimpress-ui/react';

export default function Example() {
  return (
    <Stepper orientation="vertical">
      <StepperItem description="This is the first step">Step 1</StepperItem>
      <StepperItem description="This is the current step">Step 2</StepperItem>
      <StepperItem description="This is the next step">Step 3</StepperItem>
    </Stepper>
  );
}

Copy code Open in playground

Orientation	Use cases
Horizontal	Horizontal steppers are used when there is a small number of fixed steps. To keep the width of the stepper manageable, horizontal steppers shouldn’t have more than 6 steps. If a page is limited on vertical space, use a horizontal stepper.
Vertical	Vertical steppers are best used when there is a large number of steps or when the number of steps is variable. If a page is limited on horizontal space, use a horizontal stepper.

Status

Preview

Completed:

Complete

Invalid:

Error

Warning:

Warning

In progress:

In progress

Incomplete:

Incomplete

Code

import { UNSTABLE_Stepper as Stepper, UNSTABLE_StepperItem as StepperItem } from '@cimpress-ui/react';

export default function Example() {
  return (
    <Stepper>
      <StepperItem status="complete">Complete</StepperItem>
      <StepperItem status="error">Error</StepperItem>
      <StepperItem status="warning">Warning</StepperItem>
      <StepperItem status="in-progress">In progress</StepperItem>
      <StepperItem>Incomplete</StepperItem>
    </Stepper>
  );
}

Copy code Open in playground

Status	Use cases
Incomplete	Indicates a step that has not yet been started by the user.
In progress	This step has been started but not completed by a user.
Complete	Confirms that this step has been successfully finished.
Warning	Indicates potential issues or non-critical issues within a step that a user may need to address. Warning should not be used for any errors that actively block user progress.
Error	Indicates a critical error or invalid input within a step that must be resolved before a user can continue.

Content writing

• Use concise labels that make it clear what the user will find at that step. Labels shouldn’t be more than 1 or 2 words.
• The description text should be short and provide supplemental information that’s necessary for users to know before they get to a step. If it can instead be explained within the step, don’t put it in the description.
• Legend titles can be used with steppers to provide users more context for the stepper workflow itself. Legends should be concise and easy to understand.

Behaviors

Stepper navigation

Steppers should always be used for workflows that are primarily linear. If a user is going to regularly be moving between steps or there is not a clear linear flow, stepper is not the right component to use. However, the default stepper behavior does allow users to jump back to steps they have already completed if they want to make changes. The following behavior is built into the stepper component and should not be changed to accommodate special use cases.

A step’s status indicates the current state of that step to the user. These states persist even if a user goes back to a previous step. The track bar and the label styling are used to indicate the current active step the user is on.

Nested steps

Cimpress UI does not currently support nested steps within the stepper. If you have a use case where you believe a nested stepper is the best solution, please reach out to the Cimpress UI team to let us know.