Stepper
newStep 1: draw some circles. Step 2: draw the rest of the owl. Steps that mark progress through a multi-step flow.
Open Props in the corner of the example to try color and size. size goes from xs (24px indicator) to xl (48px) and scales the indicator, its number, the gaps and the separator with it; the title and description keep their text size.
color fills the active step's indicator, in Button's colours or your own. primary is the default; neutral matches a flow whose buttons are neutral too. Completed steps and their lines stay grey, so the colour marks only where you are.
Installation
Usage
<script setup lang="ts">
import {
Stepper,
StepperIndicator,
StepperItem,
StepperSeparator,
StepperTitle,
StepperTrigger,
} from '@/components/ui/stepper'
const steps = ['Cart', 'Shipping', 'Payment']
</script>
<template>
<Stepper>
<StepperItem v-for="(title, index) in steps" :key="title" :step="index + 1" class="flex-1">
<StepperTrigger>
<StepperIndicator>{{ index + 1 }}</StepperIndicator>
<StepperTitle>{{ title }}</StepperTitle>
</StepperTrigger>
<StepperSeparator v-if="index < steps.length - 1" />
</StepperItem>
</Stepper>
</template>
Each StepperItem gets a step number, and its state follows the current step: active, completed (the steps before it, or any marked completed) or inactive. The state lands as data-state on the item, the trigger and the separator, and the indicator and the line colour themselves from it. The item is the group stepper-item, so your own parts read its state as group-data-[state=completed]/stepper-item:bg-primary.
StepperTrigger: the button; wrap a Button withas-childto style itStepperIndicator: the circle; shows "Step n" when empty and passesstepto its slotStepperTitle,StepperDescription: name and describe the triggerStepperSeparator: the line to the next step; give the itemsflex-1to space them evenly
It's linear by default: a step unlocks only once the ones before it are done. :linear="false" lets users jump anywhere.
Screen readers hear "Step n of m" on every change.
Examples
Horizontal
Buttons as triggers through as-child, with an icon for each state from the item's slot. The line is positioned across the gap between steps.
Vertical
orientation="vertical" stacks the steps, and the up and down arrows move focus. The trigger is a row with the indicator first, and a StepperSeparator placed straight in the item is a rail beside the step, from 4px under its indicator to 4px above the next one. It spans --stepper-gap, so space the steps out with that variable on the root. start-*, top-* and bottom-* on the separator move its ends: here they fit it to a 36px Button. A separator inside a wrapper of your own stays in that wrapper's flow.
Form
One Formisch form per step. Next submits the current form, so you only move on when it's valid. Clicking a later step validates the current form first, through update:modelValue. isFirstStep and isLastStep from the root slot drive the buttons.
API Reference
Every part takes a class that merges with its own.
Stepper
| Prop | Default | Type and description |
|---|---|---|
| defaultValue | — | numberThe step shown at first when |
| orientation | — | DataOrientation
|
| dir | — | DirectionReading direction. Inherits from a surrounding |
| modelValue | — | numberThe current step, counted from 1, bound with |
| linear | — | booleanSteps open in order: only the steps up to the one after the current can be reached, the rest are disabled. On by default. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| color | "primary" | StepperColor | (string & {})Colour role of the active step's indicator. Any other name picks up a colour you declare on |
| size | "md" | StepperSizeIndicator size, from 24px for |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: number | undefined]Fires when another step is selected. |
| Slot | Scope and description |
|---|---|
| default | { modelValue: number | undefined; totalSteps: number; isNextDisabled: boolean; isPrevDisabled: boolean; isFirstStep: boolean; isLastStep: boolean; goToStep: (step: number) => void; nextStep: () => void; prevStep: () => void; hasNext: () => boolean; hasPrev: () => boolean; }The items. Receives |
StepperItem
| Prop | Default | Type and description |
|---|---|---|
| step* | — | numberThe step number, counted from 1. |
| disabled | — | booleanDisables the trigger and dims the step; the arrow keys skip it. |
| completed | — | booleanMarks the step completed whatever the current step is. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { state: StepperState; }The trigger and the separator. Receives |
StepperTrigger
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the trigger's attributes, state and classes onto it. Wrap a |
| as | — | AsTag | ComponentThe element or component to render. A |
| Slot | Scope and description |
|---|---|
| default | {}The indicator, the title and the description, or anything else. |
StepperIndicator
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. A |
| Slot | Scope and description |
|---|---|
| default | { step: number; }A number or an icon. Receives |
StepperTitle
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. An |
| Slot | Scope and description |
|---|---|
| default | {}The title, which names the trigger. |
StepperDescription
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. A |
| Slot | Scope and description |
|---|---|
| default | {}The description, which the trigger is described by. |
StepperSeparator
| Prop | Default | Type and description |
|---|---|---|
| orientation | — | DataOrientationIgnored: the separator follows the stepper's orientation. |
| decorative | — | booleanIgnored: the separator is always decorative and hidden from assistive technology. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
Props
- defaultValue
numberThe step shown at first whenv-modelis not used.1by default.- orientation
DataOrientationhorizontallays the steps out in a row,verticalin a column. Arrow keys follow the orientation.- dir
DirectionReading direction. Inherits from a surroundingConfigProviderwhen not set. Otherwiseltr.- modelValue
numberThe current step, counted from 1, bound withv-model.- linear
booleanSteps open in order: only the steps up to the one after the current can be reached, the rest are disabled. On by default.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- color
"primary" StepperColor | (string & {})Colour role of the active step's indicator. Any other name picks up a colour you declare on[data-slot][data-color="<name>"]. Completed steps stay grey.- size
"md" StepperSizeIndicator size, from 24px forxsto 48px forxl, with matching icon, type, gaps and separator thickness.
Emits
- update:modelValue
[payload: number | undefined]Fires when another step is selected.
Slots
- default
{ modelValue: number | undefined; totalSteps: number; isNextDisabled: boolean; isPrevDisabled: boolean; isFirstStep: boolean; isLastStep: boolean; goToStep: (step: number) => void; nextStep: () => void; prevStep: () => void; hasNext: () => boolean; hasPrev: () => boolean; }The items. ReceivesmodelValue,totalSteps,isFirstStep,isLastStep,isNextDisabled,isPrevDisabled,hasNext,hasPrev,goToStep,nextStepandprevStep.
Props
- step*
numberThe step number, counted from 1.- disabled
booleanDisables the trigger and dims the step; the arrow keys skip it.- completed
booleanMarks the step completed whatever the current step is.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{ state: StepperState; }The trigger and the separator. Receivesstate:active,completedorinactive.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the trigger's attributes, state and classes onto it. Wrap aButtonthis way.- as
AsTag | ComponentThe element or component to render. A<button>by default.
Slots
- default
{}The indicator, the title and the description, or anything else.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. A<span>by default.
Slots
- default
{ step: number; }A number or an icon. Receivesstep. Shows "Step n" when empty.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. An<h4>by default.
Slots
- default
{}The title, which names the trigger.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. A<p>by default.
Slots
- default
{}The description, which the trigger is described by.
Props
- orientation
DataOrientationIgnored: the separator follows the stepper's orientation.- decorative
booleanIgnored: the separator is always decorative and hidden from assistive technology.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| stepper | data-orientation, data-linear, data-color, data-size, role="group" | The root, with a visually hidden live region that reads "Step n of m". |
| stepper-item | data-state, data-disabled, data-orientation, aria-current | One step; data-state is active, completed or inactive, and aria-current="true" marks the active one. |
| stepper-trigger | data-state, data-disabled, data-orientation, aria-labelledby, aria-describedby, tabindex | The button, or the child it renders with as-child; disabled while the step cannot be reached. |
| stepper-indicator | — | The circle with the number or icon. |
| stepper-title | id | The title the trigger is named by. |
| stepper-description | id | The text the trigger is described by. |
| stepper-separator | data-state, data-orientation | The line after a step, decorative. |
Keyboard
| Key | Action |
|---|---|
| Tab | Moves focus to a step that can be reached. |
| ArrowRight | Moves focus to the next step when horizontal. |
| ArrowLeft | Moves focus to the previous step when horizontal. |
| ArrowDown | Moves focus to the next step when vertical. |
| ArrowUp | Moves focus to the previous step when vertical. |
| Enter | Selects the focused step. |
| Space | Selects the focused step. |