Stepper

A visual multi-step flow guidance component where completed steps display a check icon, active steps are highlighted and enlarged, and thick-bordered circular nodes with connecting lines showcase a neo-brutalist texture.

Demo

Preview

水平

账户信息

填写基本资料

安全设置

设置密码与验证

偏好配置

个性化设置

完成

注册成功

垂直

账户信息

填写基本资料

安全设置

设置密码与验证

偏好配置

个性化设置

完成

注册成功

变体 (accent)

账户信息

填写基本资料

安全设置

设置密码与验证

偏好配置

个性化设置

完成

注册成功

尺寸 (lg)

账户信息

填写基本资料

安全设置

设置密码与验证

偏好配置

个性化设置

完成

注册成功

不可点击

账户信息

填写基本资料

安全设置

设置密码与验证

偏好配置

个性化设置

完成

注册成功

Installation

pnpm dlx brutx-vue@latest add stepper

Usage

vue

<script setup>
import { Stepper } from 'brutx-ui-vue'
import type { StepperStep } from 'brutx-ui-vue'
import { ref } from 'vue'

const steps: StepperStep[] = [
    { id: 1, title: 'Basic Info', description: 'Fill in account details' },
    { id: 2, title: 'Security', description: 'Set password' },
    { id: 3, title: 'Complete', description: 'Registration successful' },
]

const current = ref(0)
</script>

<template>
    <!-- Horizontal stepper -->
    <Stepper v-model="current" :steps="steps" orientation="horizontal" />

    <!-- Vertical stepper (supports content slots) -->
    <Stepper v-model="current" :steps="steps" orientation="vertical">
        <template #step-1>
            <p class="text-sm">Fill in step 1 content here...</p>
        </template>
        <template #step-2>
            <p class="text-sm">Fill in step 2 content here...</p>
        </template>
    </Stepper>

    <!-- Navigation buttons -->
    <button :disabled="current === 0" @click="current--">Previous</button>
    <button :disabled="current === steps.length - 1" @click="current++">Next</button>
</template>

Non-clickable

Set clickable to false to disable click-to-jump on step nodes, making them display-only.

vue

<Stepper v-model="current" :steps="steps" :clickable="false" />

Variants

Control the color of the active step using the variant prop.

Variant	Description
`default`	Default background color (`bg-brutal-bg`)
`primary`	Primary (coral) background
`accent`	Accent (yellow) background

vue

<Stepper v-model="current" :steps="steps" variant="accent" />

Sizes

Control the step node size using the size prop.

Size	Description
`sm`	Small node
`default`	Default node
`lg`	Large node

vue

<Stepper v-model="current" :steps="steps" size="lg" />

Data Types

interface StepperStep {
    id: string | number   // Unique identifier (vertical slot name is step-{id})
    title: string         // Step title
    description?: string  // Optional subtitle
}

Exported Types

import type { StepperStep } from 'brutx-ui-vue'

API Reference

Stepper — Props
Name	Type	Default	Description
`steps` Required	`StepperStep[]`	`—`	Provides ordered step data. Each item has a unique id and title, with an optional description.
Details Declared type StepperStep[] Referenced types StepperStep Type definition — StepperStep export interface StepperStep { id: string \| number; title: string; description?: string; } Default value details Not declared `—` Source Stepper.vue:20 packages/ui/src/components/stepper/Stepper.vue
`modelValue` Required	`number`	`—`	The zero-based current step index, synchronized through v-model. An out-of-range value is clamped for display state.
Details Declared type number Default value details Not declared `—` Source Stepper.vue:21 packages/ui/src/components/stepper/Stepper.vue
`orientation`	`"vertical" \| "horizontal" \| undefined`	`"horizontal"`	Sets the stepper layout direction. It defaults to horizontal; vertical mode supports step-{id} content slots for the current step.
Details Declared type "vertical" \| "horizontal" \| undefined Literal values `"horizontal"` `"vertical"` Default value details Declaration `'horizontal'` Source: packages/ui/src/components/stepper/Stepper.vue Resolved value `"horizontal"` Source Stepper.vue:22 packages/ui/src/components/stepper/Stepper.vue
`size`	`"default" \| "lg" \| "sm" \| undefined`	`"default"`	Sets the size scale for step nodes and their connectors.
Details Declared type NonNullable<"default" \| "lg" \| "sm" \| null \| undefined> \| undefined Literal values `"default"` `"lg"` `"sm"` Default value details Declaration `'default'` Source: packages/ui/src/components/stepper/Stepper.vue Resolved value `"default"` Source Stepper.vue:23 packages/ui/src/components/stepper/Stepper.vue
`variant`	`"accent" \| "default" \| "primary" \| undefined`	`"default"`	Sets the color variant used by the active step node.
Details Declared type NonNullable<"default" \| "primary" \| "accent" \| null \| undefined> \| undefined Literal values `"accent"` `"default"` `"primary"` Default value details Declaration `'default'` Source: packages/ui/src/components/stepper/Stepper.vue Resolved value `"default"` Source Stepper.vue:24 packages/ui/src/components/stepper/Stepper.vue
`clickable`	`boolean \| undefined`	`true`	Allows a step node to be clicked to navigate to that step.
Details Declared type boolean \| undefined Literal values `false` `true` Default value details Declaration `true` Source: packages/ui/src/components/stepper/Stepper.vue Resolved value `true` Source Stepper.vue:25 packages/ui/src/components/stepper/Stepper.vue
`class`	`string \| undefined`	`undefined`	Additional CSS classes applied to the stepper root container.
Details Declared type string \| undefined Default value details Declaration `undefined` Source: packages/ui/src/components/stepper/Stepper.vue Resolved value `undefined` Source Stepper.vue:26 packages/ui/src/components/stepper/Stepper.vue

Stepper — Events
Name	Signature or type	Description
`@update:modelValue`	`[step: number]`	Emits the new valid step index when the current step changes so v-model can be synchronized.
Details Declared type [step: number] Source Stepper.vue packages/ui/src/components/stepper/Stepper.vue
`@step-click`	`[index: number]`	Emitted with the clicked node’s zero-based index when a step node is clicked.
Details Declared type [index: number] Source Stepper.vue packages/ui/src/components/stepper/Stepper.vue

Stepper — Exposes
Name	Signature or type	Description
`currentStep`	`number`	The read-only current step index. It is -1 when there are no steps and otherwise stays within the valid step range.
Details Declared type number Source Stepper.vue:91 packages/ui/src/components/stepper/Stepper.vue
`totalSteps`	`number`	The read-only total number of steps, equal to the length of steps.
Details Declared type number Source Stepper.vue:92 packages/ui/src/components/stepper/Stepper.vue
`goToStep`	`(index: number) => void`	Requests navigation to an index and emits an update only when the index is within the existing step range.
Details Declared type (index: number) => void Source Stepper.vue:93 packages/ui/src/components/stepper/Stepper.vue
`nextStep`	`() => void`	Requests the next step; it emits no update when the list is empty or the current step is already last.
Details Declared type () => void Source Stepper.vue:94 packages/ui/src/components/stepper/Stepper.vue
`previousStep`	`() => void`	Requests the previous step; it emits no update when the list is empty or the current step is already first.
Details Declared type () => void Source Stepper.vue:95 packages/ui/src/components/stepper/Stepper.vue
`isFirstStep`	`boolean`	A read-only boolean indicating whether the current step is first; it is false for an empty list.
Details Declared type boolean Literal values `false` `true` Source Stepper.vue:96 packages/ui/src/components/stepper/Stepper.vue
`isLastStep`	`boolean`	A read-only boolean indicating whether the current step is last; it is false for an empty list.
Details Declared type boolean Literal values `false` `true` Source Stepper.vue:97 packages/ui/src/components/stepper/Stepper.vue

Slots

In vertical mode, each step can inject content via the #step-{id} slot when active:

html

<Stepper v-model="current" :steps="steps" orientation="vertical">
    <template #step-1>
        <!-- Content displayed when step 1 is active -->
    </template>
</Stepper>

Accessibility

Keyboard: Step buttons support arrow key navigation (←/→ in horizontal mode, ↑/↓ in vertical mode), Home/End to jump to the first/last step, Enter/Space to click the currently focused step
Focus Management: Step buttons can be focused via the Tab key

Node State Reference

State	Style	Condition
`completed`	Green background + checkmark icon	Index < current step
`active`	Variant background color + large shadow	Index = current step
`upcoming`	Default background color + semi-transparent	Index > current step

Exposed Methods (defineExpose)

See the API reference above for instance methods and read-only state. Call instance methods through a ref:

Access the component instance via ref to call the following methods:

Stepper ​

Demo ​

Installation ​

Usage ​

Non-clickable ​

Variants ​

Sizes ​

Data Types ​

Exported Types ​

API Reference ​

Declared type

Default value details

Source

Declared type

Default value details

Source

Declared type

Default value details

Source

Declared type

Default value details

Source

Declared type

Default value details

Source

Declared type

Default value details

Source

Declared type

Default value details

Source

Declared type

Source

Declared type

Source

Declared type

Source

Declared type

Source

Declared type

Source

Declared type

Source

Declared type

Source

Declared type

Source

Declared type

Source

Slots ​

Accessibility ​

Node State Reference ​

Exposed Methods (defineExpose) ​

Stepper

Demo

Installation

Usage

Non-clickable

Variants

Sizes

Data Types

Exported Types

API Reference

Slots

Accessibility

Node State Reference

Exposed Methods (defineExpose)