◇

Stepper

7 parts

A multi-step progress control that guides users through a sequence of steps — checkout flows, onboarding wizards, or any task split into ordered stages. Use it when you need to show where the user is, which steps are done, and (optionally) let them jump between steps. The root owns the active step (1-based), tracks the total via the Collection, arbitrates linear vs. free navigation, handles roving keyboard focus across triggers, and provides context to every StepperItem.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  StepperRoot,
  StepperItem,
  StepperTrigger,
  StepperIndicator,
  StepperTitle,
  StepperDescription,
  StepperSeparator,
} from '@robonen/primitives/forms/stepper';

<StepperRoot>
  <StepperItem />
  <StepperTrigger />
  <StepperIndicator />
  <StepperTitle />
  <StepperDescription />
  <StepperSeparator />
</StepperRoot>

API Reference

StepperRoot

Root

Prop	Type	Default	Description
`defaultValue`?	`number`	`1`	Uncontrolled initial step.
`orientation`?	`StepperOrientation`	`'horizontal'`	Orientation.
`dir`?	`StepperDirection`	—	Writing direction. Falls back to `ConfigProvider` when omitted.
`linear`?	`boolean`	`true`	Require steps to be completed in order.
`disabled`?	`boolean`	—	Disable the entire stepper.
`announceLabel`?	`(state: { value: number; total: number }) => string`	({ value, total }) => `Step ${value} of ${total}`	Builds the message announced to screen readers via the visually-hidden live region whenever the active step changes. Override for i18n.
`modelValue`?	`number`	—	Two-way bound value (`v-model`).

Emits

Event	Payload
`update:modelValue`	`[value: number]`

StepperItem

Item

A single step within the stepper. Associates its child trigger, indicator, title, and description with a step number and derives that step's state (`active`, `completed`, or `inactive`) from the root's current value.

Prop	Type	Default	Description
`step`	`number`	—	1-based index associating this item with a step.
`disabled`?	`boolean`	—	Disable this specific step.
`completed`?	`boolean`	—	Mark the step as completed regardless of current `modelValue`.

StepperTrigger

Trigger

The interactive control for a step. Clicking or pressing it navigates to the step (subject to the root's `linear` and `disabled` rules) and it participates in roving arrow-key focus across all enabled triggers.

No props or events — renders its element and forwards attributes.

StepperIndicator

Indicator

The visual marker for a step — typically a numbered circle or check. Defaults to rendering the step number, and exposes the current `step` and `state` via slot props so you can swap in icons (e.g. a check when completed).

No props or events — renders its element and forwards attributes.

StepperTitle

Title

The accessible label for a step. Its `id` is wired to the trigger's `aria-labelledby`, so screen readers announce it when the trigger is focused.

No props or events — renders its element and forwards attributes.

StepperDescription

Description

Optional supporting text for a step. Its `id` is wired to the trigger's `aria-describedby` so it is announced as a description of the step.

No props or events — renders its element and forwards attributes.

StepperSeparator

Separator

The decorative connector drawn between adjacent steps. It is `aria-hidden` and exposes the owning item's `state` and the stepper `orientation` as data attributes so the line can be styled to reflect progress.

Prop	Type	Default	Description
`orientation`?	`StepperOrientation`	—	Override the connector orientation. Defaults to the stepper's own orientation, so you usually do not need to set it.