Milestone Unlock Meter

全幅進度量表：液面隨數據或捲動上升充滿整個區塊，每越過一個門檻，對應的里程碑卡片即彈出解鎖並亮起。

載入預覽⋯

Playground

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

充填進度（%）value

主題色accent

液面波動wave

充填動畫時長（秒）duration

1.2

<MilestoneUnlockMeter />

安裝

npx shadcn@latest add https://webberui.com/r/milestone-unlock-meter.json

或在 components.json 設定 registries 後，改用 @webberui/milestone-unlock-meter 安裝。

安裝依賴後，從 registry JSON（/r/milestone-unlock-meter.json 的 files[0].content）複製 milestone-unlock-meter.tsx 原始碼到你的 components/ui/ 目錄：

npm install motion lucide-react clsx tailwind-merge

使用

以 Milestone 子元件宣告各個門檻，MilestoneUnlockMeter 依 mode 決定液面來源。

資料模式

由 value（0–100）驅動液面高度，數值變動時平滑補間，越過門檻的卡片自動解鎖。

import {
  Milestone,
  MilestoneUnlockMeter,
} from "@/components/ui/milestone-unlock-meter";
import { Rocket, Star, Trophy, Zap } from "lucide-react";

<MilestoneUnlockMeter mode="data" value={64} accent="emerald" height={440}>
  <Milestone threshold={12} title="啟動" description="建立第一個專案" icon={<Zap className="size-4" />} />
  <Milestone threshold={40} title="加速" description="累積 100 位使用者" icon={<Rocket className="size-4" />} />
  <Milestone threshold={68} title="亮眼成長" description="達成 1,000 次互動" icon={<Star className="size-4" />} />
  <Milestone threshold={92} title="里程碑達成" description="解鎖全部成就" icon={<Trophy className="size-4" />} />
</MilestoneUnlockMeter>

捲動模式

mode="scroll" 時液面高度綁定量表區塊在視窗（或捲動容器）中的進度：往下捲動液面上升，經過每個門檻即解鎖對應卡片。若量表位於巢狀的 overflow-y-auto 容器內，請把該容器的 ref 傳給 container。

const scrollerRef = React.useRef<HTMLDivElement>(null);

<div ref={scrollerRef} className="h-[300px] overflow-y-auto">
  <MilestoneUnlockMeter mode="scroll" container={scrollerRef} height={300} scrollLength={2.4}>
    {/* Milestone... */}
  </MilestoneUnlockMeter>
</div>;

Props

`MilestoneUnlockMeter`

Prop	型別	預設值	說明
`children`	`ReactNode`	—	放入 `Milestone` 子元件
`mode`	`"data" \| "scroll"`	`"data"`	液面驅動來源：資料或捲動進度
`value`	`number`	`0`	`data` 模式的目標充填百分比（0–100）
`height`	`number`	`440`	量表面板高度（px）
`scrollLength`	`number`	`2`	`scroll` 模式捲動軌道相對面板高度的倍數，越大需捲越久
`accent`	`"emerald" \| "blue" \| "violet" \| "amber" \| "neutral"`	`"emerald"`	主題色
`wave`	`boolean`	`true`	是否顯示液面波動動畫
`duration`	`number`	`1.2`	`data` 模式充填動畫時長（秒）
`container`	`RefObject<HTMLElement \| null>`	—	`scroll` 模式的巢狀捲動容器 ref
`ariaLabel`	`string`	`"里程碑解鎖量表"`	量表的無障礙標籤
`className`	`string`	—	外層容器樣式
`panelClassName`	`string`	—	量表面板樣式（邊框、圓角、底色）
`fillClassName`	`string`	—	液面色塊樣式

`Milestone`

Prop	型別	預設值	說明
`threshold`	`number`	—	解鎖門檻（0–100），液面高於此值即解鎖
`title`	`ReactNode`	—	里程碑標題
`description`	`ReactNode`	—	里程碑描述
`icon`	`ReactNode`	打勾	解鎖後顯示的圖示
`className`	`string`	—	卡片樣式

細節

每個 Milestone 依 threshold 絕對定位於面板高度對應的百分比位置，並以自身中心對齊液面，因此門檻刻度、標尺與卡片三者精準對齊。
液面高度、標尺充填與進度讀數共用同一個 MotionValue，逐格更新不觸發 React re-render；只有在跨越門檻（解鎖狀態翻轉）時才重繪對應卡片。
建議 threshold 落在約 10–95 之間，讓卡片在面板內完整顯示、不被上下緣裁切。
data 模式以 animate 補間到 value；scroll 模式以 useSpring 平滑捲動進度，讓液面上升更順。

可及性

使用者系統開啟「減少動態效果」時，停用波動與彈跳動畫，狀態切換即時完成；液面仍會依資料或捲動呈現，僅移除多餘動態。
量表容器帶 role="group" 與 aria-label；里程碑以 <ol>／<li> 表達順序清單，每張卡片的 aria-label 會朗讀標題、解鎖狀態與門檻百分比。
液面、波峰、標尺與進度讀數等純裝飾元素皆標記 aria-hidden，不干擾輔助科技朗讀。

Milestone Unlock Meter

On this page