Stepper

Accessible, unstyled Stepper primitive for multi-step flows.


Package	`@vizejs/ui/stepper`
Maturity	stable
Own the source	`vize lib pull stepper`
Requires	collection, composite-navigation, context, controllable-state, id, typeahead
Aliases	stepper, wizard, multi-step flow, checkout steps
Covers	WAI-ARIA aria-current step, MUI Stepper, Vuetify Stepper, Reka UI Stepper

Usage

import { Stepper, StepperRoot, StepperContent, StepperItem, StepperList, StepperTrigger } from "@vizejs/ui/stepper";

Or copy the source into your project with vize lib pull stepper (see Source Distribution).

API

`Stepper`

Source: src/families/navigation/stepper/stepper-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned Stepper base id. `null` and `undefined` select a deterministic fallback.
`modelValue`	`StepperValue`	`undefined`	Controlled current step value. `undefined` selects uncontrolled behavior; `null` clears it.
`defaultValue`	`StepperValue`	`undefined`	Initial current step for uncontrolled use. `undefined` selects the first enabled step.
`disabled`	`boolean`	`false`	Disable every step trigger while preserving the current content panel.
`navigationMode`	`StepperNavigationMode`	`"linear"`	Whether future steps require every previous enabled step to be completed.
`orientation`	`StepperOrientation`	`"horizontal"`	Directional layout hint used by arrow-key navigation.
`dir`	`StepperDirection`	`"ltr"`	Reading direction used for horizontal arrow-key navigation.
`loop`	`boolean`	`false`	Whether arrow-key navigation wraps at the first and last enabled trigger.

Events

Event	Payload	Description
`update:modelValue`	`[value: StepperValue]`	Fired when the current step requests a new controlled value.
`change`	`[value: StepperValue, previous: StepperValue, nativeEvent: Event \| null]`	Fired after any distinct current-step request.

Slots

Slot	Slot props	Description
`default`	`StepperSlotState`	Compound Stepper children. Receives current value, completion, and navigation state.

Exposed

Member	Type	Description
`completedValues`	—
`currentIndex`	—
`dir`	—
`disabled`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—
`id`	—
`isSelectable`	—
`listId`	—
`navigationMode`	—
`next`	—
`orientation`	—
`previous`	—
`reset`	—
`selectValue`	—
`setValue`	—
`state`	—
`value`	—

`StepperRoot`

Source: src/families/navigation/stepper/stepper-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned Stepper base id. `null` and `undefined` select a deterministic fallback.
`modelValue`	`StepperValue`	`undefined`	Controlled current step value. `undefined` selects uncontrolled behavior; `null` clears it.
`defaultValue`	`StepperValue`	`undefined`	Initial current step for uncontrolled use. `undefined` selects the first enabled step.
`disabled`	`boolean`	`false`	Disable every step trigger while preserving the current content panel.
`navigationMode`	`StepperNavigationMode`	`"linear"`	Whether future steps require every previous enabled step to be completed.
`orientation`	`StepperOrientation`	`"horizontal"`	Directional layout hint used by arrow-key navigation.
`dir`	`StepperDirection`	`"ltr"`	Reading direction used for horizontal arrow-key navigation.
`loop`	`boolean`	`false`	Whether arrow-key navigation wraps at the first and last enabled trigger.

Events

Event	Payload	Description
`update:modelValue`	`[value: StepperValue]`	Fired when the current step requests a new controlled value.
`change`	`[value: StepperValue, previous: StepperValue, nativeEvent: Event \| null]`	Fired after any distinct current-step request.

Slots

Slot	Slot props	Description
`default`	`StepperSlotState`	Compound Stepper children. Receives current value, completion, and navigation state.

Exposed

Member	Type	Description
`completedValues`	—
`currentIndex`	—
`dir`	—
`disabled`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—
`id`	—
`isSelectable`	—
`listId`	—
`navigationMode`	—
`next`	—
`orientation`	—
`previous`	—
`reset`	—
`selectValue`	—
`setValue`	—
`state`	—
`value`	—

`StepperContent`

Source: src/families/navigation/stepper/stepper-content.vue

Props

Prop	Type	Default	Description
`value` (required)	`string`	`required`	Content value paired with a StepperItem.
`role`	`StepperContentRole \| null`	`"region"`	Optional landmark role for the content. `null` renders a plain `div`.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label or `aria-labelledby` supplies one.
`ariaLabelledby`	`string \| null`	`undefined`	Space-separated ids that label the panel. `null` omits the default trigger id.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the panel.

Slots

Slot	Slot props	Description
`default`	`StepperContentSlotState`	Panel contents. Receives current visibility, orientation, and availability state.

Exposed

Member	Type	Description
`value`	`string`	Content value paired with a StepperItem and StepperTrigger.
`current`	`boolean`	Whether this content panel is paired with the current step.
`active`	`boolean`	Whether this content panel is currently visible.
`completed`	`boolean`	Whether the paired step is marked completed.
`disabled`	`boolean`	Whether the Stepper root or paired item is disabled.
`orientation`	`StepperOrientation`	Directional layout hint inherited from the Stepper root.
`state`	`StepperContentState`	Stable state token for styling and tests.
`element`	`HTMLDivElement \| null`	Rendered content panel element.
`id`	`string`	Deterministic id wired from content to trigger.
`triggerId`	`string`	Deterministic id of the controlling trigger.
`focusContent`	`(options?: FocusOptions) => void`	Move focus to the visible content panel.

`StepperItem`

Source: src/families/navigation/stepper/stepper-item.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned list item id. `null` and `undefined` select a deterministic fallback.
`value` (required)	`string`	`required`	Stable step value used for selection and collection identity.
`completed`	`boolean`	`false`	Mark this step as completed for styling and linear navigation.
`disabled`	`boolean`	`false`	Disable this step while preserving the rest of the Stepper.
`textValue`	`string \| null`	`undefined`	Explicit text used by future collection search or virtualized trigger labels.
`order`	`number`	`undefined`	Deterministic order for virtualized, portalled, or server-only steps.
`ariaLabel`	`string`	`undefined`	Accessible name when no list item text supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label this list item.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe this list item.

Slots

Slot	Slot props	Description
`default`	`StepperItemSlotState`	Step contents. Receives current, completion, and activation state.

Exposed

Member	Type	Description
`value`	`string`	Step value used for current-step state and collection identity.
`index`	`number`	Index within all registered StepperItem instances.
`current`	`boolean`	Whether this step is the current step.
`completed`	`boolean`	Whether this step is marked completed.
`disabled`	`boolean`	Whether this step or its root is disabled.
`selectable`	`boolean`	Whether this step may be activated under the current navigation mode.
`locked`	`boolean`	Whether a linear Stepper is preventing activation of this otherwise enabled step.
`orientation`	`StepperOrientation`	Directional layout hint inherited from the Stepper root.
`navigationMode`	`StepperNavigationMode`	Whether step activation is linear or free-form.
`state`	`StepperItemState`	Stable state token for styling and tests.
`element`	`HTMLDivElement \| null`	Rendered list item element.
`id`	`string`	Deterministic id assigned to the item.
`triggerId`	`string`	Deterministic id wired from trigger to content.
`contentId`	`string`	Deterministic id wired from content to trigger.
`focus`	`(options?: FocusOptions) => boolean`	Move focus to this step's trigger when it can receive focus.
`select`	`() => boolean`	Request this step as the current value.

`StepperList`

Source: src/families/navigation/stepper/stepper-list.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label or `aria-labelledby` supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the step list.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the step list.

Slots

Slot	Slot props	Description
`default`	`StepperListSlotState`	StepperItem children. Receives the current root and list state.

Exposed

Member	Type	Description
`value`	`StepperValue`	Current step value, or `null` when no step is current.
`completedValues`	`readonly string[]`	Values whose StepperItem is marked completed.
`currentIndex`	`number`	Current step index within all registered items, or `-1` when empty or missing.
`disabled`	`boolean`	Whether every trigger is disabled by the root.
`navigationMode`	`StepperNavigationMode`	Whether step activation is linear or free-form.
`orientation`	`StepperOrientation`	Directional layout hint for ARIA and consumer-owned styles.
`dir`	`StepperDirection`	Reading direction used for horizontal keyboard navigation.
`state`	`StepperRootState`	Stable state token for styling and tests.
`listId`	`string`	Deterministic id assigned to the list.
`element`	`HTMLDivElement \| null`	Rendered list element.
`focus`	`(options?: FocusOptions) => void`	Move focus to the current, active, or first enabled trigger.

`StepperTrigger`

Source: src/families/navigation/stepper/stepper-trigger.vue

Props

Prop	Type	Default	Description
`type`	`"button" \| "reset" \| "submit"`	`"button"`	Native button submission behavior.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label or `aria-labelledby` supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the trigger.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the trigger.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before this trigger requests selection. Call `preventDefault()` to keep state unchanged.

Slots

Slot	Slot props	Description
`default`	`StepperTriggerSlotState`	Trigger contents. Receives current, completion, and activation state.
`indicator`	`StepperTriggerSlotState`	Optional completion/current indicator controlled by the consumer.

Exposed

Member	Type	Description
`value`	`string`	Step value used for current-step state and collection identity.
`index`	`number`	Index within all registered StepperItem instances.
`current`	`boolean`	Whether this step is the current step.
`completed`	`boolean`	Whether this step is marked completed.
`disabled`	`boolean`	Whether this step or its root is disabled.
`selectable`	`boolean`	Whether this step may be activated under the current navigation mode.
`locked`	`boolean`	Whether a linear Stepper is preventing activation of this otherwise enabled step.
`orientation`	`StepperOrientation`	Directional layout hint inherited from the Stepper root.
`navigationMode`	`StepperNavigationMode`	Whether step activation is linear or free-form.
`state`	`StepperItemState`	Stable state token for styling and tests.
`element`	`HTMLButtonElement \| null`	Rendered native trigger button.
`id`	`string`	Deterministic id wired from trigger to content.
`contentId`	`string`	Deterministic id of the controlled content panel.
`focus`	`(options?: FocusOptions) => void`	Move focus to the native trigger button.
`select`	`() => boolean`	Request this step as the current value.

Behavior

Normative state x input -> outcome table for stepper-root.vue, stepper-list.vue, stepper-item.vue, stepper-trigger.vue, and stepper-content.vue (@vizejs/ui/stepper). Every row in this isolated slice is proven by the named focused tests; registry, package exports, renderer fixtures, and size budgets are intentionally left for the parent integration step.

ID	State	Input	Outcome	Evidence
S1	default / current	render	root, list, item, trigger, and content expose deterministic ids, ARIA wiring, slots, and data	`renders accessible stepper semantics with deterministic ids, slots, and data`
S2	linear / future pending	click	focusable future triggers advertise `aria-disabled` and do not emit or change value until prior steps complete	`linear navigation prevents future activation until prior enabled steps are complete`
S3	linear / reset default	reset	imperative reset restores the configured default even when normal linear activation is currently locked	`reset restores the configured default value even when linear activation is locked`
S4	dynamic item value	prop update	item registration, trigger ids, content ids, and fallback current value update when a step value changes	`items reregister when their step value changes`
S5	free / disabled item	Arrow key, then Enter	roving focus skips natively disabled steps and native keyboard activation selects any enabled step	`free navigation and roving focus can activate any enabled step while skipping disabled`
S6	controlled	click	emits the requested value while rendered current state stays controlled until parent accepts it	`controlled current value wins until the parent accepts the request`
S7	disabled root / item	click or Tab	disabled triggers leave activation and sequential focus while preserving content state	`disabled roots and items suppress user activation and sequential focus`
S8	exposed instances	focus, next, previous	public refs expose element state and imperative focus/value methods	`exposes typed state and imperative focus/value controls`
S9	optional content role	render	content can render without a landmark role or default trigger label	`content can opt out of the region role and default trigger label`
S10	missing provider	setup	compound parts fail closed with the shared context diagnostic	`compound parts require matching Stepper providers`
S11	SSR and hydration	isolated render/mount	generated ids are byte-identical per request and hydrate without replacement warnings	`stepper-ssr.test.ts`

navigationMode="linear" allows the current step, previous enabled steps, and future enabled steps only when every prior enabled step is marked completed. Linear-locked future triggers remain roving-focusable with aria-disabled so the flow remains discoverable; true root or item disabled states use native disabled buttons and are skipped by keyboard navigation. Content panels retain stable markup for hydration, use hidden while inactive, and default aria-labelledby to the paired trigger id when a landmark role is present.