團購成團進度（React）

台灣社群團、辦公室團最常見的「湊人數」介面：商品列顯示目前團購價——跟團人數每跨過一個階梯門檻，舊價劃線、新價由下往上滾入；進度條以人數為刻度，每個階梯門檻都有節點與價籤；已跟團者以名字首字＋確定性色相的頭像堆疊呈現（最多 6 位＋「+N」，新成員從右側滑入）；成團倒數每秒更新。按「+1 跟團」呼叫 onJoin，達成團門檻的瞬間 CTA 變成「已成團 🎉」、整卡輕微 scale 脈動並噴出彩帶粒子；截止仍未達門檻則自動轉為未成團，顯示「未成團將全額退款」。狀態支援受控／非受控。

Playground

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

<GroupBuyProgress />

安裝

npx shadcn@latest add https://webberui.com/r/group-buy-progress.json

使用

import * as React from "react";
import {
  GroupBuyProgress,
  type GroupBuyParticipant,
} from "@/components/ui/group-buy-progress";

function OfficeCoffeeGroupBuy() {
  // 名單由你的資料層維護；元件只讀取，按「+1 跟團」時透過 onJoin 通知你新增
  const [participants, setParticipants] = React.useState<GroupBuyParticipant[]>([
    { id: "u1", name: "林曉彤" },
    { id: "u2", name: "陳建宏" },
    { id: "u3", name: "黃雅琪" },
  ]);

  return (
    <GroupBuyProgress
      product={{ name: "手沖濾掛咖啡 12 入組", subtitle: "深焙", price: 520 }}
      tiers={[
        { count: 5, price: 450 },
        { count: 10, price: 399 },
      ]}
      participants={participants}
      deadline="2026-09-30T23:59:59+08:00"
      maxSpots={20}
      onJoin={() =>
        setParticipants((list) => [...list, { id: "me", name: "我" }])
      }
      onFormed={() => console.log("成團了，通知主購結單")}
      onChange={(status) => console.log("狀態：", status)}
    />
  );
}

Props

GroupBuyStatus

"open" | "formed" | "failed"——募集中／已成團／未成團。

GroupBuyProduct

GroupBuyTier

GroupBuyParticipant

GroupBuyProgressLabels

含 {count}／{price} 的字串會在顯示時代入實際值。

另外具名匯出 resolveGroupBuyTier(tiers, count)（回傳目前落在的階與下一階）與 formatGroupBuyPrice(amount, currency)（千分位金額字串），方便在購物車或結帳頁沿用同一套價格規則。

細節

• 價格落階：目前單價 = 已達到的最高階價格，未達任何階時為 product.price。價格一變，前一個價格就成為劃線舊價（初始已達階時舊價為原價），新價從下方滾入
• 進度刻度：滿刻度為 maxSpots；未提供時取最高階人數與成團門檻的較大者。每個階梯在軌道上都有節點與「人數／價格」籤；兩端的籤自動靠邊對齊，不會凸出軌道
• 成團與未成團：非受控模式下，募集中人數達 minCount 即自動轉為 formed；deadline 到期仍未達門檻則轉為 failed。受控模式元件只透過 onChange 建議下一個狀態，由你決定是否更新 value。成團與未成團都是終態，之後不會再自動改變
• 倒數：Date.now() 只在 effect 內讀取；SSR 與首次渲染顯示 -- 佔位，掛載後才每秒更新，避免水合不一致。無效的 deadline 會隱藏倒數且永不到期
• 頭像：不用圖片；底色由 id 雜湊出色相（同一人每次相同），也可用 color 指定。堆疊顯示最新加入的 maxAvatars 位，較早的成員彙整為「+N」

可及性

• 進度條為 role="progressbar"，aria-valuenow／aria-valuemax 以人數為單位，aria-valuetext 朗讀「N 人已跟團」；人數文字置於 aria-live="polite" 區域，跟團後會被螢幕閱讀器朗讀
• 倒數為 role="timer"，aria-label 提供完整的「天／時／分／秒」文字；未成團的退款提示為 role="status"
• 頭像堆疊為語意 list，每位成員的 li 帶名字，「+N」帶「還有 N 人」；視覺首字對輔助科技隱藏
• 跟團按鈕為原生 button（type="button"），成團／未成團／額滿時 disabled 並同步 aria-disabled；鍵盤操作與 focus-visible 外框沿用瀏覽器原生行為
• 使用者系統開啟「減少動態效果」時，停用價格滾動、頭像滑入、整卡脈動與彩帶粒子，只保留即時的文字與顏色變化