Skip to content

Stepper

Guide someone through a sequence of steps.

Demos

Size

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Panels share one grid area by default, reserving room for the tallest retained panel and fading in over 180ms. Inactive panels stay hidden from interaction. If you enable unmountOnHide, use ui.panels to reserve any minimum height your layout needs.

Installation

Complete the shared installation. Copy Stepper.vue and index.ts into app/components/ui/stepper/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Props

PropTypeDefaultDescription
itemsStepperItem[]requiredStep data.
valueKeystring"value"Custom item value key.
titleKeystring"title"Custom title key.
descriptionKeystring"description"Custom description key.
disabledKeystring"disabled"Custom disabled key.
completedKeystring"completed"Custom completed key.
linearbooleantrueRequires ordered progression.
disabledbooleanfalseDisables all step triggers.
loopbooleanfalseLoops roving keyboard focus.
orientation"horizontal" | "vertical""horizontal"Layout and arrow-key axis.
activationMode"manual" | "automatic""manual"Whether arrow focus also changes active step.
showControlsbooleanfalseRenders generated previous/next buttons.
unmountOnHidebooleanfalseUnmounts inactive panels instead of hiding them.
dir"ltr" | "rtl""ltr"Horizontal keyboard direction.
ariaLabelstring"Progress steps"Accessible ordered-list label.
uiStepperUi—Classes for structural parts.

Slots

SlotPropsDescription
item / item slotitem, index, value, state, isActive, isCompleted, isDisabled, selectEntire trigger body.
indicatoritem, index, stateGenerated indicator content.
titleitem, indexAccessible title content.
descriptionitem, indexAccessible description content.
optionalitem, indexOptional label content.
separatoritem, index, isCompletedConnector content.
panelitem, index, valueShared panel content.
panel-[value]item, index, value, isActiveValue-specific panel content.
previousdisabled, previousPrevious button content.
nextdisabled, nextNext button content.
statecurrent state and all navigation methodsOptional state-driven custom controls.

Events

EventPayloadDescription
update:modelValuevalueFired after an accepted step change.
value-change(value, details)Fired before step activation. details.cancel() prevents it.
complete(value, details)Fired when the final item becomes active.

Keyboard

KeyBehavior
ArrowRight / ArrowLeftMove roving focus horizontally, respecting RTL.
ArrowDown / ArrowUpMove roving focus vertically.
HomeFocus first permitted step.
EndFocus last permitted step.
Enter / SpaceActivate focused step in manual mode.

With activationMode="automatic", arrow-key focus also activates the destination step.