Stepper

Workflow steps with current, complete, upcoming, and error states.

Overview

  • Show progress through an ordered workflow. Configure whether users can select a step.

Aliases

progress steps

When to use

  • Use Stepper when the user is moving through a clear ordered workflow or reviewing overall step status.
  • Use explicit status labels when the workflow includes incomplete or error states.

When not to use

  • Do not use Stepper when the flow can branch in several directions.
  • Do not use Stepper for shell navigation where sections are not genuinely sequential.

Structural parts

progress connector

track

Visual connector between steps.

step marker

indicator

Shows completion or current-state emphasis.

step title

label

Names the step clearly.

Public interface

Props
NameTypeDefaultDescription
itemsArray<{ id: string; label: string; description?: string; status?: "complete" | "current" | "upcoming" | "error" }>—Ordered step definitions.
valuestring—Controlled active step ID.
orientation'horizontal' | 'vertical''horizontal'Chooses step layout orientation.
interactivebooleanfalseAllows the user to change steps directly.
onChange(detail: { value: string }) => void—Receives the new active step value.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
change{ value: string }Fires with the active step value.
Slots
NameDescription
defaultStepper is data-driven and does not expose compound step slots.

Variants, sizes, and states

Variants

  • horizontal: Default row of steps
  • vertical: Stacked step progression for narrower or denser layouts

Sizes

  • sm: Compact stepper
  • md: Default stepper

States

  • complete: Step already finished
  • current: Current step
  • upcoming: Future step
  • error: Step needs attention

Accessibility

Semantics

  • Uses ordered step semantics through a navigation-like structure with visible status cues.

Keyboard

  • When step selection is enabled, each step is keyboard reachable.

Screen readers

  • Identify step status with labels and state cues as well as color.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-stepper-gap
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

track

--dk-stepper-track-color
#95989d
--dk-stepper-track-thickness
2px
--dk-stepper-track-gap
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

item

--dk-stepper-item-bg
#f2f5fb
--dk-stepper-item-fg
#16181c
--dk-stepper-item-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-stepper-item-block-size
44px
--dk-stepper-item-inline-padding
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

indicator

--dk-stepper-indicator-bg
#e5e8ed
--dk-stepper-indicator-fg
#16181c
--dk-stepper-indicator-size
1.5rem

label

--dk-stepper-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-stepper-label-weight
650

description

--dk-stepper-description-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-stepper-description-color
#16181c

Implementation notes

  • Use Stepper for a linear workflow.

Examples

Starter

Ordered workflow progress

A standard horizontal workflow stepper.

<Stepper items={steps} value="review" />

Common patterns

Vertical progress rail

Vertical orientation works well in side panels and setup flows.

<Stepper items={steps} value="review" orientation="vertical" />

Edge cases

Clickable step navigation

Enable direct step changes only when revisiting steps is part of the workflow.

<Stepper items={steps} value={currentStep} interactive={true} onChange={(detail) => currentStep = detail.value} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

horizontal-md

pass

orientation=horizontal|size=md

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 98.5 Lc
  • Target: 44 px

vertical-sm

pass

orientation=vertical|size=sm

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 98.5 Lc
  • Target: 44 px

selected-md

pass

orientation=horizontal|size=md

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 89.9 Lc
  • Target: 44 px