Stepper

SStepper shows progress through a sequence of steps (checkout, a setup wizard). The active step is highlighted, completed ones are marked with a check. It is controlled with v-model (the step number, starting at 1); the indicators are clickable and support arrow-key navigation — Reka handles focus and ARIA. The orientation is horizontal or vertical, and the step label can sit on any of the four sides of the indicator (label-placement).

Basic usage

Step 2 of 0

<script setup>
import { ref } from 'vue'
const step = ref(2)
const items = [
  { title: 'Shipping', description: 'Address and method' },
  { title: 'Payment', description: 'Card or invoice' },
  { title: 'Confirmation', description: 'Review your order' },
]
</script>

<template>
  <SStepper
    v-model="step"
    :items="items"
  />
</template>

Vertical orientation

Step 1 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    orientation="vertical"
  />
</template>

Label placement

label-placement sets the side of the indicator where the title and description go: top and bottom put them above and below the circle, start and end before and after it (left and right in a left-to-right layout). The prop works in both orientations, and the default depends on the orientation: a horizontal stepper puts the label below, a vertical one to the right. With a side label the step becomes a row, and the connector becomes a link between steps.

Horizontal layout

Step 2 of 0

Step 2 of 0

Step 2 of 0

Step 2 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    label-placement="bottom"
  />
  <SStepper
    v-model="step"
    :items="items"
    label-placement="top"
  />
  <SStepper
    v-model="step"
    :items="items"
    label-placement="end"
  />
  <SStepper
    v-model="step"
    :items="items"
    label-placement="start"
  />
</template>

Vertical: beside the indicator

On the left is end, the default for the vertical layout; on the right is start: the circles move to the right edge and the labels to the left.

Step 2 of 0

Step 2 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    orientation="vertical"
    label-placement="end"
  />
  <SStepper
    v-model="step"
    :items="items"
    orientation="vertical"
    label-placement="start"
  />
</template>

Vertical: above and below the indicator

The step becomes a centered column, as in the horizontal layout: the label is centered on the circle, and the circles and connectors stay on one axis even when labels differ in width.

Step 2 of 0

Step 2 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    orientation="vertical"
    label-placement="top"
  />
  <SStepper
    v-model="step"
    :items="items"
    orientation="vertical"
    label-placement="bottom"
  />
</template>

Responsive layout

A horizontal stepper needs room: at a narrow width the labels shrink until they wrap by words, and beyond that the steps no longer fit. stack-at sets a width in pixels below which the stepper switches to vertical — arrow-key navigation and data-orientation change together with the orientation, so this is a real layout change, not a CSS rotation.

The threshold is compared with the width of the stepper itself, not the window: in a side column or a modal it gets cramped even on a wide screen, where a media query would notice nothing. Without the prop the layout never changes.

Step 2 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    :stack-at="640"
  />
</template>

To check it, narrow the browser window: below 640px this stepper becomes vertical.

narrow-orientation sets the orientation below the threshold (vertical by default). Combined with orientation="vertical" it gives the reverse layout: a column where there is room — for example, in a side column of a form — and a row above the form when space is tight. Below 480px this stepper turns into a row.

Step 2 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    orientation="vertical"
    :stack-at="480"
    narrow-orientation="horizontal"
  />
</template>

Step icons

The icon field of a step replaces the number in the indicator, and done-icon sets the icon of a completed step (both take a registry name or a raw path).

Step 2 of 0

<script setup>
import { ref } from 'vue'
const step = ref(2)
const items = [
  { title: 'Account', description: 'Profile details', icon: 'user' },
  { title: 'Payment', description: 'Card or invoice', icon: 'credit-card' },
  { title: 'Done', description: 'Order placed', icon: 'circle-check' },
]
</script>

<template>
  <SStepper
    v-model="step"
    :items="items"
    done-icon="check"
  />
</template>

Linear mode

linear requires going through the steps strictly in order — you cannot jump ahead to an unfinished step (the indicators of future steps are not clickable). Unavailable steps are not dimmed, though: the stepper works as a table of contents, and the names of future steps must stay readable. Only a step explicitly disabled with the disabled field is dimmed.

Step 1 of 0

<script setup>
import { ref } from 'vue'
const step = ref(1)
const items = [
  { title: 'Shipping', description: 'Address and method' },
  { title: 'Payment', description: 'Card or invoice' },
  { title: 'Confirmation', description: 'Review your order' },
]
</script>

<template>
  <SStepper
    v-model="step"
    :items="[...items, { title: 'Card payment', description: 'Unavailable', disabled: true }]"
    linear
  />
</template>

Color

The color prop sets the color of the active/completed step and the connector from the palette. By default the current step gets a pale background with an accent border; active-variant="filled" fills it with the accent, like completed steps.

Step 2 of 0

Step 2 of 0

<template>
  <SStepper
    v-model="step"
    :items="items"
    color="indigo"
  />
  <SStepper
    v-model="step"
    :items="items"
    active-variant="filled"
  />
</template>

API

Props

Name	Type	Default	Description
items*	{ title: string; description?: string; icon?: string; disabled?: boolean }[]	required	List of steps. Indicators are numbered automatically, starting from 1.
color	string	undefined	Accent color (active/completed step): a name from the palette (primary/teal/teal-10).
text-color	string	undefined	Color of the content on the completed step fill: a name from the palette. White by default.
orientation	"vertical" | "horizontal"	"horizontal"	Layout orientation of the steps. It also sets the direction of arrow key navigation.
label-placement	| "start" | "top" | "bottom" | "end"	undefined	Side of the indicator where the step label goes: top and bottom are above and below the circle, start and end are before and after it (left and right in a left-to-right layout). Works in both orientations. Without a value the label is below in the horizontal layout and on the right in the vertical one — there is no shared default, otherwise changing the orientation would move the label.
stack-at	number	undefined	Width in pixels below which a horizontal stepper switches to vertical. It is compared with the width available to the stepper, not the window: in a narrow column or a modal the layout breaks even on a wide screen. Without the prop the layout never changes.
narrow-orientation	"vertical" | "horizontal"	"vertical"	Orientation below the stack-at threshold. vertical by default; horizontal together with orientation="vertical" gives the reverse: a column when wide and a row when narrow.
active-variant	"tonal" | "filled"	"tonal"	Style of the current step: tonal is a pale background with an accent border, filled is an accent fill, like completed steps.
linear	boolean	false	Requires completing steps strictly in order (no skipping ahead). Unavailable steps are not dimmed: future step titles stay readable.
done-icon	string	"check"	Icon of a completed step (a registry name or a raw path).
model-value	number	1	Current active step (1-based). Two-way binding via v-model.

Events

Name	Signature	Description
update:modelValue	(value: number) => void	Emitted when modelValue changes. Used for two-way binding (v-model).