步驟進度指示器 Stepper｜免費 React 元件

獨立的多步驟進度 stepper 指示器，支援勾號描繪、連接線填充與活躍脈動。

以圓點與連接線呈現多步驟流程進度，完成的步驟顯示勾號、連接線平滑填滿，活躍步驟帶脈動指示。支援水平與垂直排列。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add stepper

Stepper 是用 React、Motion（motion/react）與 Tailwind CSS 做的步驟條（stepper／流程進度指示）元件，支援水平與垂直排列：已完成的步驟顯示勾號、連接線依進度填滿，目前步驟外圈有脈動提示。它只負責顯示進度，切換步驟的狀態由你傳入的 current 決定。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

目前步驟current

排列方向orientation

圓點直徑size

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<Stepper/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

適用情境

結帳頁頂端標示「購物車、填寫資料、付款、完成」目前走到哪一步
訂單或物流追蹤頁，用垂直排列列出每個處理階段
帳號開通、KYC 驗證這類要分好幾天完成的流程狀態
後台的部署或審核流程進度
不適合：步驟內容要在同一個容器裡切換、還需要上一步／下一步按鈕時，改用 Multi-step Form

安裝

npx webberui@latest add https://webberui.com/r/stepper.json

或在 components.json 設定 registries 後，改用 @webberui/stepper 安裝。

使用

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

const steps = [
  { title: "帳號", description: "建立登入資訊" },
  { title: "個人資料", description: "填寫基本資料" },
  { title: "完成", description: "確認並送出" },
];

<Stepper steps={steps} current={1} />;

current 為 0-based 索引：小於它的步驟視為完成，等於它的為活躍，大於它的為未完成。

範例

垂直排列的訂單進度

orientation="vertical" 讓標籤排在圓點右側，description 可以放時間或補充說明。

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

const orderSteps = [
  { title: "訂單成立", description: "10/12 14:32" },
  { title: "已出貨", description: "10/13 09:10，黑貓宅急便" },
  { title: "配送中" },
  { title: "已送達" },
];

<Stepper steps={orderSteps} current={2} orientation="vertical" size={28} />;

搭配按鈕切換步驟

Stepper 本身不可點擊，用你自己的 state 驅動 current。

"use client";

import * as React from "react";
import { Stepper } from "@/components/ui/stepper";

const steps = [
  { title: "購物車" },
  { title: "填寫資料" },
  { title: "付款" },
];

export function CheckoutProgress() {
  const [current, setCurrent] = React.useState(0);

  return (
    <div className="space-y-6">
      <Stepper steps={steps} current={current} />
      <button
        onClick={() => setCurrent((c) => Math.min(c + 1, steps.length))}
        className="rounded-lg bg-neutral-900 px-4 py-2 text-sm text-white"
      >
        下一步
      </button>
    </div>
  );
}

全部完成

current 設成 steps.length 時，所有步驟都顯示為完成，沒有活躍中的步驟。

<Stepper steps={steps} current={steps.length} />

Props

Prop	型別	預設值	說明
`steps`	`StepperStep[]`	—	步驟清單，每項含 `title` 與選填 `description`
`current`	`number`	—	目前步驟索引（0-based）；小於它的步驟為完成
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	排列方向
`size`	`number`	`36`	圓點直徑（px），連接線對齊其中心
`className`	`string`	—	透傳至最外層容器

StepperStep 型別為 { title: string; description?: string }。

可及性

容器帶 role="list" 與 aria-label，各步驟為 role="listitem"
活躍步驟帶 aria-current="step"
使用者系統開啟「減少動態效果」時，關閉脈動與描繪動畫，直接呈現最終狀態

常見問題

可以在 Next.js App Router 使用嗎？

可以，檔案開頭已有 "use client"。首次渲染與 SSR 一致，掛載後才依「減少動態效果」設定切換成靜態版本。

使用者可以點擊步驟跳回去嗎？

不行，Stepper 只負責顯示。需要點擊回跳，請改用 Multi-step Form，它的進度指示可以回到已完成的步驟。

怎麼調整大小？

用 size 設定圓點直徑（預設 36px），數字字級、勾號大小與水平模式的標籤寬度都會跟著換算。

支援減少動態效果嗎？

支援。系統開啟「減少動態效果」時，脈動、縮放與連接線描繪動畫都會關閉，直接呈現最終狀態。

需要哪些依賴？

motion、lucide-react、clsx 與 tailwind-merge。也可以從安裝區塊的「手動」分頁直接複製原始碼。

Stepper

把這個效果裝進你的專案

本頁目錄