Group Buy Progress (React)

The classic "let's get enough people" interface of Taiwanese community and office group buys: the product row shows the current group price — every time the head count crosses a tier threshold the old price gets struck through and the new one rolls in from below; the progress bar is scaled in people, with a node and price tag at every tier; participants appear as a stack of initial-letter avatars with deterministic hues (up to 6 plus "+N", new members slide in from the right); the deadline countdown ticks every second. Pressing "+1 跟團" (join) calls onJoin; the instant the minimum is reached the CTA becomes "已成團 🎉" (group formed), the whole card pulses slightly and confetti bursts out. If the deadline passes without reaching the minimum the card switches to failed and shows "未成團將全額退款" (full refund if the group does not form). The status supports both controlled and uncontrolled modes.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<GroupBuyProgress />

Installation

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

Usage

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

function OfficeCoffeeGroupBuy() {
  // Your data layer owns the roster; the component only reads it and asks you
  // to append a member through onJoin when "+1 跟團" is pressed
  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("Group formed — tell the organizer to close the order")}
      onChange={(status) => console.log("status:", status)}
    />
  );
}

Props

GroupBuyStatus

"open" | "formed" | "failed" — recruiting, group formed, group failed.

GroupBuyProduct

GroupBuyTier

GroupBuyParticipant

GroupBuyProgressLabels

Strings containing {count} / {price} have the actual values substituted at render time.

resolveGroupBuyTier(tiers, count) (returns the tier currently reached and the next one) and formatGroupBuyPrice(amount, currency) (thousands-grouped amount string) are also named exports, so the cart or checkout page can reuse the exact same pricing rule.

How it works

• Tier pricing: the current unit price is the price of the highest tier reached, or product.price before any tier. Whenever the price changes, the previous price becomes the struck-through one (the list price when a tier is already reached at mount) and the new price rolls in from below
• Progress scale: the full scale is maxSpots; when omitted it is the larger of the highest tier count and the minimum. Every tier gets a node on the track plus a "count / price" tag; tags at the two ends automatically align to the edge so they never spill past the track
• Formed and failed: in uncontrolled mode the card switches to formed as soon as the head count reaches minCount while open, and to failed if deadline passes short of it. In controlled mode the component only suggests the next status through onChange and you decide whether to update value. Formed and failed are terminal — the card never changes automatically after that
• Countdown: Date.now() is only read inside an effect; SSR and the first render show -- placeholders and the numbers start ticking after mount, so hydration stays consistent. An invalid deadline hides the countdown and never expires
• Avatars: no images; the background hue is hashed from id (stable per person), or set explicitly with color. The stack shows the most recent maxAvatars joiners and folds earlier ones into "+N"

Accessibility

• The progress bar is role="progressbar" with aria-valuenow / aria-valuemax in people and aria-valuetext reading "N 人已跟團" (N people joined); the head-count text lives in an aria-live="polite" region, so screen readers announce it after each join
• The countdown is role="timer" with a full "days / hours / minutes / seconds" aria-label; the refund note when the group fails is role="status"
• The avatar stack is a semantic list; each member's li carries the name and "+N" carries "N more people"; the visual initial is hidden from assistive technology
• The join button is a native button (type="button"); when formed, failed, or full it is disabled with aria-disabled kept in sync, and keyboard behavior plus the focus-visible outline follow the browser defaults
• When the user has "reduce motion" enabled at the system level, the price roll, avatar slide-in, card pulse, and confetti are disabled and only the instant text and color changes remain