Stepper

new

Step 1: draw some circles. Step 2: draw the rest of the owl. Steps that mark progress through a multi-step flow.

Demo

Address

Add your address

Shipping

Set your preferred

Payment

Add any payment

Checkout

Confirm your order

Step 1 of 0

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 with as-child to style it
  • StepperIndicator: the circle; shows "Step n" when empty and passes step to its slot
  • StepperTitle, StepperDescription: name and describe the trigger
  • StepperSeparator: the line to the next step; give the items flex-1 to 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.

Horizontal

Your details

Provide your name and email

Company details

A few details about your company

Invite your team

Start collaborating with your team

Step 1 of 0

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.

Vertical

Your details

Provide your name and email address. We will use this information to create your account.

Company details

A few details about your company will help us personalise your experience.

Invite your team

Start collaborating with your team by inviting them to join your account. You can skip this step and invite them later.

Step 1 of 0

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.

Form

Your details

Provide your name and email

Your password

Choose a password

Your favourite drink

Choose a drink

Step 1 of 0

API Reference

Every part takes a class that merges with its own.

Data attributes

data-slotAttributesDescription
stepperdata-orientation, data-linear, data-color, data-size, role="group"The root, with a visually hidden live region that reads "Step n of m".
stepper-itemdata-state, data-disabled, data-orientation, aria-currentOne step; data-state is active, completed or inactive, and aria-current="true" marks the active one.
stepper-triggerdata-state, data-disabled, data-orientation, aria-labelledby, aria-describedby, tabindexThe 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-titleidThe title the trigger is named by.
stepper-descriptionidThe text the trigger is described by.
stepper-separatordata-state, data-orientationThe line after a step, decorative.

Keyboard

KeyAction
TabMoves focus to a step that can be reached.
ArrowRightMoves focus to the next step when horizontal.
ArrowLeftMoves focus to the previous step when horizontal.
ArrowDownMoves focus to the next step when vertical.
ArrowUpMoves focus to the previous step when vertical.
EnterSelects the focused step.
SpaceSelects the focused step.

Changelog

  1. registry 0.22.0

    aac2ce3 — Breaking: StepperItem is the named group group/stepper-item instead of a bare group, and the indicator and separator read their state through group-data-[state=…]/stepper-item: and group-data-disabled/stepper-item:. An outer element with the group class and a data-state (an outer step of a nested stepper, your own wrapper) no longer paints the steps inside it. Classes you copied from the examples as group-data-[state=completed]:bg-primary need the new suffix: group-data-[state=completed]/stepper-item:bg-primary.

    fc19419 — A thickness class on StepperSeparator (h-1 across a horizontal stepper, w-1 down a vertical one) now wins; the separator takes its size-driven thickness through --stepper-separator-h and --stepper-separator-w instead of data-[orientation] rules that outranked the class.

    c0f96e5 — A vertical Stepper draws its separators as a rail: a StepperSeparator placed straight in a StepperItem runs beside the step from 4px under the indicator to 4px above the next one, where it used to stretch across the row and come out 0px tall. The vertical trigger is a row with the indicator first. The rail spans --stepper-gap, the space between steps, and start-*, top-* and bottom-* on the separator move it. stepperItem and stepperTrigger are now stepperItemVariants and stepperTriggerVariants, which take the orientation. Horizontal steppers are unchanged.

  2. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  3. registry 0.19.0

    adf96cd — Parts no longer style themselves from their root's size through group-data-[size=…] variants, which beat any plain class of yours. size is the density of the root, and a class on a part wins:

    - Card, Empty, Alert and Stepper: CardTitle, CardDescription, EmptyTitle, EmptyDescription, AlertTitle, AlertDescription, StepperTitle and StepperDescription keep one text size at every root size (title-md/body-md, title-sm/body-md for Alert, title-sm/body-sm for Stepper). Empty's icon and gaps and Stepper's indicator number still follow the size, through --empty-icon, --empty-header-gap, --empty-content-gap and --stepper-text on the root. - Menu and DrawerMenu labels, Menubar triggers and the Calendar heading, weekday cells and week numbers keep scaling with the size, through --menu-label, --menubar-text, --calendar-heading and --calendar-label (each with a -leading twin) set by the root. - AlertDialog size="sm" centres its text through the content, so text-start on AlertDialogHeader wins; the footer keeps its two-column grid.

  4. registry 0.13.0

    5a478d3 — Checkbox, Radio, Switch, Slider, Progress, Stepper and TabsList take color: primary (the default), neutral, destructive, success, warning, info, or any name you declare on [data-slot][data-color="<name>"], as on Button. The root carries data-color. Whatever they draw straight on the page takes the colour's --tone-text: a checked edge, the radio's dot, the default slider's range and thumb, the progress bar and the tab line. That keeps a bright success, warning or info at 3:1 against the page. Fills with something on them, like the checked box, the switch track and the active step, keep --tone. On the choice controls the unchecked edge stays --input and an invalid control still turns destructive. Keyboard focus rings a control in a colour other than primary in its --tone-text, red once it's invalid. CheckboxGroup and RadioGroup pass their color to every control in them without one, and ChoiceGroup takes color for the selected card's edge, the focused card's ring and the selected row's tint. Switch, Checkbox, Radio and Slider now set data-size, md by default. They need the @kappa-ui/core release that lets tone-control follow data-color.

    Recoloured Switch, Checkbox, Radio or Slider with class="[--tone:…] [--tone-foreground:…]", as the theming page used to suggest? Their edges and marks now read --tone-text, so add [--tone-text:…] to the class, or use color.

  5. registry 0.8.0

    657321c — Stepper: Stepper, StepperItem, StepperTrigger, StepperIndicator, StepperTitle, StepperDescription and StepperSeparator over Reka UI's stepper, shaped after shadcn-vue. The indicator and the separator colour themselves from the step's state, the stepper is linear by default, and one size from xs to xl scales the indicator, its icon, the type, the gaps and the separator.