components / stepper

Stepper

Ordered progress and workflow navigation surface with current, complete, upcoming, and error step semantics.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Stepper makes multi-step workflows legible without turning them into full-blown wizard chrome.
  • It supports both horizontal and vertical step layouts while keeping state language consistent.

Aliases

progress steps

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Stepper when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Stepper contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Stepper label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Stepper behind decorative copy or overloaded surface treatments.
  • Do not stretch Stepper into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • 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.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • 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.

Anti-patterns

  • Using Stepper as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy stepper usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

progress connector

track

Visual connector between steps.

step marker

indicator

Shows completion or current-state emphasis.

step title

label

Names the step clearly.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
itemsArray<{ id: string; label: string; description?: string; status?: "complete" | "current" | "upcoming" | "error" }>—Ordered step definitions.
valuestring—Controlled current step id.
orientation'horizontal' | 'vertical''horizontal'Chooses step layout orientation.
interactivebooleanfalseAllows the user to change steps directly.
onChange(detail: { id: string }) => void—Callback fired when the active step changes.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
change{ id: string }Fires when the active step changes.

Slots

NameDescription
defaultStepper is data-driven in v1 and does not expose compound step slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

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

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

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

Keyboard

  • Interactive steppers should remain keyboard reachable when step selection is enabled.

Screen readers

  • Current, complete, upcoming, and error step meaning should be understandable from text and state cues.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

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

  • Stepper assumes a linear workflow. If the flow can branch or nest, a different navigation model is usually clearer.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
expanded

Starter

1 example

starter

Starter: ordered workflow progress

A standard horizontal workflow stepper.

Copy snippet

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

Common patterns

1 example

common

Common: vertical progress rail

Vertical orientation works well in side panels and setup flows.

Copy snippet

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

Edge cases

1 example

edge

Edge: clickable step navigation

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

Copy snippet

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

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

horizontal-md

pass

orientation=horizontal|size=md

  • Contrast: 98.5 Lc
  • Target: 44px

vertical-sm

pass

orientation=vertical|size=sm

  • Contrast: 98.5 Lc
  • Target: 44px

selected-md

pass

orientation=horizontal|size=md

  • Contrast: 89.9 Lc
  • Target: 44px