Chuyển tới nội dung
werewolf-ui
Component

Stepper

Shows the steps of a flow in order and where the user is (checkout, onboarding, setup). Completed steps are buttons that go back to that step; upcoming steps cannot be reached from here. Use Tabs for switching views, not for a sequence.

Xem trước

  2. 2Shipping, current step
  3. 3Payment, not reached

Props

  • orientation
import { Stepper } from "@/components/ui/stepper"

<Stepper steps={checkoutSteps} current={1} onStepSelect={goToStep} />

Cách dùng

Khi nào dùng

  • Show where someone is in an ordered flow such as checkout, onboarding or setup.
  • Let someone return to a completed step without opening upcoming steps early.

Khi nào không dùng

  • Switch between views of the same content. Use Tabs.
  • Show how much work is complete without naming sequential steps. Use Progress.
  • Navigate between pages or sections. Use Sidebar or BottomNav.

Biến thể

orientation

Row or column. Use vertical below md when labels do not fit, or in a side column.

    2. 2Shipping, current step
    3. 3Payment, not reached

    horizontalmặc định

    2. 2Shipping, current step
    3. 3Payment, not reached

    vertical

import { Stepper } from "@/components/ui/stepper"

<Stepper steps={checkoutSteps} current={1} onStepSelect={goToStep} />
<Stepper orientation="vertical" steps={checkoutSteps} current={1} onStepSelect={goToStep} />

Ví dụ

Checkout

  2. 2Shipping, current step
  3. 3Payment, not reached
import { Stepper } from "@/components/ui/stepper"

<Stepper current={1} steps={checkoutSteps} onStepSelect={goToStep} />

Vertical with descriptions

  1. 1Account, current stepEmail and password
  2. 2Team, not reachedInvite people
import { Stepper } from "@/components/ui/stepper"

<Stepper orientation="vertical" current={0} steps={setupSteps} />

Nên và không nên

Nên

  • Keep labels to one or two words.
  • Use 3 to 7 steps; more needs grouping.
  • Show the step count in the page heading too (Step 2 of 4) when the Stepper is hidden on small screens.

Không nên

  • Do not use Tabs for a sequence the user must follow in order.
  • Do not use as navigation to steps the user has not reached.

Props

TênKiểuGiá trịMặc địnhMô tả
steps bắt buộc{ id: string; label: string; description?: string; status?: "error"; icon?: React.ReactNode }[]--The steps in order. icon replaces the number in a current or upcoming step. status error overrides the computed visual state of that step.
current bắt buộcnumber--Zero-based index of the current step. Steps before it are complete.
orientationenumhorizontal | verticalhorizontalRow or column. Use vertical below md when labels do not fit, or in a side column.
onStepSelect(index: number) => void--Called with the index when a completed step is activated, to go back to it. Required by the type when current is greater than zero, because an earlier step can be activated.
statusLabels{ completed?: string; current?: string; upcoming?: string; error?: string; goBack?: (label: string) => string }--Words added to each step's accessible name, as {label}, {status}: { completed, current, upcoming, error }. Defaults: completed, current step, not reached, has an error. Vietnamese: đã xong, bước hiện tại, chưa đến, có lỗi. goBack names a completed step button: EN `{label}, completed, go back to this step`, VI `{label}, đã xong, quay lại bước này`.

Slot

TênBắt buộcMô tả
stepIconkhôngOptional custom icon per step, replacing the number (not the check or error icon).

Cấu tạo

PhầnMô tả
rootThe ol that lays out the steps in a row or a column.
stepOne li: indicator, label, optional description.
indicatorThe 24px circle with the step number, a check when complete, or a warning icon on error.
labelThe step title, font-size-md, medium weight on the current step.
descriptionOptional secondary line under the label.
connectorThe line between two indicators; accent once the earlier step is complete.

Khả năng truy cập

Role: list

PhímHành động
TabMoves to the next completed step (a button). The current and upcoming steps are not focusable.
Enter / SpaceGoes back to the focused completed step through onStepSelect.
  • An ordered list. The current step has aria-current="step" and sets data-current.
  • A completed step is a button named EN `{label}, completed, go back to this step`, VI `{label}, đã xong, quay lại bước này`.
  • Each step's accessible text includes its state word (completed, current, upcoming, error) from statusLabels, not only the icon or color.
  • The connector lines are decorative (aria-hidden).
  • Steps with an error show a danger icon and the word from statusLabels.error.

Cài đặt

npx werewolf-ui add stepper

Chạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.