HyStepper

Usage examples on this page are written for Lit / plain HTML (<hy-stepper>). The same component ships as HyStepper in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

Child components: <hy-step> — used only inside this one.

An ordered, accessible progress stepper. Orchestrates a slotted set of hy-step children: it renders the step rail (indicators, labels, connectors), owns keyboard navigation and the active-step state machine, gates which steps can be reached (linear vs. non-linear), and emits a cancelable before-change plus a change event.

Accessibility: built in

The rail is an ordered navigation list — <nav aria-label> → <ol> → <li> per step — NOT a tablist. The current step carries aria-current="step"; completed / upcoming status is conveyed by a visually-hidden text label per step. This is the convergent accessible-stepper pattern (USWDS, Carbon, PatternFly, WAI-ARIA aria-current guidance), not the tab pattern.

Accessibility: your part

• Set label to the task the steps belong to, such as "Checkout"; the default is only "Progress".

Controlled

active-step is controlled, like hy-tab-group's active-panel. The stepper emits intent (before-change, cancelable) and the resulting change; the consumer owns which step is active. The stepper self-manages each child's derived status (completed / active / upcoming), preserving a non-current step that the consumer flagged status="error".

Keyboard

• Arrow Right/Left (horizontal) or Down/Up (vertical): move focus between navigable steps (roving tabindex).
• Home / End: first / last navigable step.
• Enter / Space / Click: activate the focused step (subject to gating and the before-change veto).

When to use

• A task of three to seven steps done in order: a checkout, an onboarding, a setup.
• Steps people may visit in any order before they finish, with non-linear.

Do

• Name each step by what it covers, in a word or two.
• Mark a step that needs attention with its error state.

When not to use

• Sections people switch between in any order: hy-tab-group.
• Reporting how far a task has got, with no step navigation: hy-progress.
• A dated record of what happened: hy-timeline.
• Where the page sits in a site or document hierarchy: hy-breadcrumb.
• A narrow column, or a long list of steps: orientation="vertical".
• Moving between steps: put Back and Next hy-buttons in each step's content and drive active-step from them; the stepper draws none.

Examples

Linear wizard

<hy-stepper active-step="0" label="Checkout">
  <hy-step label="Cart"><p>…</p></hy-step>
  <hy-step label="Shipping"><p>…</p></hy-step>
  <hy-step label="Payment"><p>…</p></hy-step>
</hy-stepper>

API

Properties

Property	Attribute	Type	Default	Description
activeStep	active-step	number	0	The controlled, 0-indexed active step.
orientation	orientation	'horizontal' | 'vertical'	'horizontal'	Rail layout direction.
labelPlacement	label-placement	'inline' | 'bottom'	'inline'	Where the label sits relative to the indicator (horizontal only).
nonLinear	non-linear	boolean	false	When true, any non-disabled step is reachable; otherwise only steps up to active-step + 1.
label	label	string	'Progress'	Accessible name for the <nav> landmark.
strings	—	Partial<StepperStrings>	{}	The built-in strings, merged over DEFAULT_STEPPER_STRINGS — set only the keys you translate. Use for internationalization.

Events

Event	Detail	Description
change	—	Fired when the user or a navigation method (next / previous / goTo / reset) changes the active step. Not fired for a direct active-step assignment or on mount. Detail: { activeStep: number, previousStep: number }
before-change	—	Cancelable. Fired on a user-initiated step change before change. Call event.preventDefault() to veto (e.g. block advancing until the current step validates). Not fired for programmatic active-step updates. Detail: { activeStep: number, previousStep: number }

Slots

Slot	Description
default	The hy-step children.

CSS Parts

Part	Description
base	The <nav> landmark wrapper.
rail	The ordered list of steps.
content	The active step's content region.

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-stepper-indicator-size-lg	var(--hy-indicator-size-lg)	Diameter of the step indicator.
--hy-stepper-gap-row-nav-md-block	var(--hy-gap-row-nav-md-block)	Gap between the rail and the content region.
--hy-stepper-border-default-rest	var(--hy-border-default-rest)	Connector line color (incomplete).
--hy-stepper-background-success-indicator-rest	var(--hy-background-success-indicator-rest)	Connector line color (complete).

Methods

next()

Advance to the next step. Returns true if it moved.

previous()

Go back one step. Returns true if it moved.

goTo()

Jump to a specific step (subject to gating + before-change). Returns true if it moved.

reset()

Reset to the first step and clear any error statuses. Always succeeds; emits change when the step actually moves.