Stepper | Calcite Design System

Steppers are used to show context and linear progress through a workflow.

Overview

Stepper has the ability to display a variety of applications with Stepper Items, such as completed steps. Functionally similar to Tabs, Stepper switches content in the display based on which step the user is on. Stepper can be used in vertical or horizontal layouts.

Sample

Usage

Multiple step workflows
Onboarding experiences

Component comparison

Stepper, Tabs, and Navigation may look similar, but each supports a distinct type of user flow and interaction.

Stepper

This component

Best for guiding users through processes with sequential steps.

Interactions typically advance users to a next step, either within the same page or to a different page.

Tabs

Alternative

Best for grouping related content into separate sections.

Interactions typically switch content within same page.

Navigation

Alternative

Best for navigating an application.

Interactions typically take users to a different page.

Best practices

Below are important guidelines on using the Stepper component.

Do use Stepper for complex workflows.

Avoid using Stepper for simple workflows.

Correct Vertical Stepper in small spaces

Consider a "vertical" layout when space is limited.

Consider a "horizontal-single" layout when space is limited, but a horizontal Stepper is preferred.

Accessibility

Key	Function
`Arrow left`	Moves focus to the previous non-disabled `calcite-stepper-item`. If the current focus and selection is the first `calcite-stepper-item`, focus will cycle to the last `calcite-stepper-item`.
`Arrow right`	Moves focus to the next non-disabled `calcite-stepper-item`. If the current focus and selection is the last `calcite-stepper-item`, focus will cycle to the first `calcite-stepper-item`.
`Arrow down`	Moves focus to the next non-disabled `calcite-stepper-item`. If the current focus and selection is the last `calcite-stepper-item`, focus will cycle to the first `calcite-stepper-item`.
`Arrow up`	Moves focus to the previous non-disabled `calcite-stepper-item`. If the current focus and selection is the first `calcite-stepper-item`, focus will cycle to the last `calcite-stepper-item`.
`Home`	Moves focus to first non-disabled `calcite-stepper-item`.
`End`	Moves focus to last non-disabled `calcite-stepper-item`.
`Space`	Selects the currently focused `calcite-stepper-item`.
`Enter`	Selects the currently focused `calcite-stepper-item`.
`Tab`	Moves focus to next non-disabled `calcite-stepper-item`. If the currently focused `calcite-stepper-item` is the last `calcite-stepper-item`, focus will leave the component.
`Tab` and `Shift`	Moves focus to previous non-disabled `calcite-stepper-item`. If the currently focused `calcite-stepper-item` is the first `calcite-stepper-item`, focus will leave the component.

Writing and copy

Do use concise headings.

Avoid wordy or overly descriptive headings.

API reference

Properties

Property	Attribute	Description	Type	Default
icon	icon	When `true`, displays a status icon in the `calcite-stepper-item` heading.	`boolean`	`false`
layout	layout	Defines the component's layout.	`StepperLayout`	`"horizontal"`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
numbered	numbered	When `true`, displays the step number in the `calcite-stepper-item` heading.	`boolean`	`false`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization.	`NumberingSystem \| undefined`
scale	scale	Specifies the component's size.	`Scale`	`"m"`
selectedItemread-only		Specifies the component's selected item.	`StepperItem`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-stepper-item`s.

Events

Name	Description	Behavior
calciteStepperChange	Fires when the active `calcite-stepper-item` changes.	bubblescomposed

Styles

Name	Description
--calcite-stepper-bar-gap	Specifies the space between the component's `calcite-stepper-item`s.
--calcite-stepper-bar-inactive-fill-color	Specifies the `calcite-stepper-item`s' bar fill color of the component's `calcite-stepper-item`s.
--calcite-stepper-bar-active-fill-color	Specifies the `calcite-stepper-item`s' bar fill color of the component's active `calcite-stepper-item`s.
--calcite-stepper-bar-complete-fill-color	When `calcite-stepper-item`s are `complete`, specifies the component's `calcite-stepper-item`s' bar fill color.
--calcite-stepper-bar-error-fill-color	When `calcite-stepper-item`s contain an `error`, specifies the component's `calcite-stepper-item`s' bar fill color.

Methods

Name	Description	Signature
componentOnReady	Create a promise that resolves once component is fully loaded.	`componentOnReady(): Promise<this>`
endStep	Set the last `calcite-stepper-item` as active.	`endStep(): Promise<void>`
goToStep	Set a specified `calcite-stepper-item` as active.	`goToStep(step: number): Promise<void>`
nextStep	Set the next `calcite-stepper-item` as active.	`nextStep(): Promise<void>`
prevStep	Set the previous `calcite-stepper-item` as active.	`prevStep(): Promise<void>`
startStep	Set the first `calcite-stepper-item` as active.	`startStep(): Promise<void>`