Multi Step Loader
長任務逐步勾選的清單式載入指示。
清單式的載入覆蓋層：逐步推進、把已完成的步驟勾選起來，並讓目前步驟平滑置中，上下邊緣淡出。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
1500
5
<MultiStepLoader />
安裝
npx shadcn@latest add https://webberui.com/r/multi-step-loader.json或在 components.json 設定 registries 後，改用 @webberui/multi-step-loader 安裝。
安裝依賴後，從 registry JSON（/r/multi-step-loader.json 的 files[0].content）複製 multi-step-loader.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion lucide-react clsx tailwind-merge使用
覆蓋層預設鋪滿最近的定位祖先，所以把它放進一個 relative 容器即可。用 loading 這個受控 prop 控制顯示。
import * as React from "react";
import { MultiStepLoader } from "@/components/ui/multi-step-loader";
const steps = ["連線到伺服器", "驗證身份", "同步資料", "準備就緒"];
export function Example() {
const [loading, setLoading] = React.useState(false);
return (
<div className="relative h-80 w-full">
<button onClick={() => setLoading(true)}>開始</button>
<MultiStepLoader
steps={steps}
loading={loading}
onComplete={() => setLoading(false)}
/>
</div>
);
}每一步停留 duration 毫秒後推進。非循環模式抵達最後一步時會觸發 onComplete，讓你在收尾後把 loading 設回 false。
Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
steps | string[] | — | 逐步顯示並依序勾選的載入文案 |
loading | boolean | — | 是否顯示載入覆蓋層（受控） |
duration | number | 1500 | 每一步停留時間（毫秒） |
loop | boolean | false | 抵達最後一步後是否從頭循環 |
visibleRows | number | 5 | 可視區容納的列數，決定覆蓋層高度與上下淡出範圍 |
overlay | boolean | true | true 鋪滿定位祖先；false 為內嵌卡片 |
onComplete | () => void | — | 非循環且抵達最後一步時觸發一次 |
className | string | — | 透傳到覆蓋層容器 |
自訂
- 用
--wb-loader-accentCSS 變數改變勾選圓圈的強調色，預設為翠綠#10b981。 overlay={false}時元件呈現為帶邊框的內嵌卡片，適合放在流程面板裡。
可及性
- 覆蓋層帶
role="status"與aria-live="polite"，目前步驟以隱藏文字朗讀為「步驟名稱（第 n／總數）」。 - 拆分後的清單對輔助科技以
aria-hidden隱藏，避免重複朗讀。 - 使用者系統開啟「減少動態效果」時，置中位移與旋轉動畫改為瞬時切換。