Stepper

Stepper represents progress through a multi-step process. It renders an ordered list, connects each trigger to a panel, and supports linear or free navigation.

Stepper coordinates navigation. Application code owns step validation and persistence.

Anatomy

• #item: Replaces one generated trigger body. Per-item named slots are supported through item.slot.
• #indicator: Step number or status visual.
• #title: Accessible step title.
• #description: Optional accessible step description.
• #optional: Optional-step label.
• #separator: Connector between adjacent steps.
• #panel: Shared panel content for each item.
• #panel-[value]: Value-specific panel content.
• #previous: Previous control content when showControls is enabled.
• #next: Next control content when showControls is enabled.
• #state: Optional renderless current-step state and navigation actions.

Titles, descriptions, triggers, and panels receive unique SSR-safe ids. Keep title content meaningful because it labels the generated trigger and panel.

Usage

<script setup lang="ts">
import { Stepper } from "akaza-ui";
import { ref } from "vue";

const step = ref(1);
const items = [
  { value: 1, title: "Account", content: "Account details" },
  { value: 2, title: "Workspace", content: "Workspace settings" },
  { value: 3, title: "Review", content: "Review request" },
];
</script>

<template>
  <Stepper v-model="step" :items="items" show-controls />
</template>

Examples

Linear flow

Linear mode is enabled by default. Users can revisit completed steps or advance one step, but cannot skip unfinished steps.

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

Non-linear flow

Disable linear when every enabled step can be opened directly.

<template>
  <Stepper v-model="step" :items="items" :linear="false" />
</template>

Vertical orientation

Vertical orientation switches arrow navigation to Up and Down and exposes matching orientation data attributes.

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

Completed, optional, and disabled items

Item metadata can override derived completion or block a step. Disabled steps are skipped by roving focus.

<script setup lang="ts">
const items = [
  { value: "account", title: "Account", completed: true },
  { value: "profile", title: "Profile", optional: true },
  { value: "billing", title: "Billing", disabled: true },
];
</script>

<template>
  <Stepper v-model="step" :items="items" :linear="false" />
</template>

Application validation

Cancel a proposed step change until application validation passes. Akaza does not hide workflow validation inside the visual primitive.

<template>
  <Stepper
    v-model="step"
    :items="items"
    @value-change="(_value, details) => {
      if (!currentStepIsValid) details.cancel()
    }"
  />
</template>

API Reference

Model

Item shape

Props

Emits

Slots

Methods

UI Options

Styling Hooks

Plain class applies to the root wrapper. Use ui.trigger, ui.indicator, and ui.panel for the main generated parts.

Keyboard

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