規格色票選擇器

電商商品頁的規格選擇器：顏色色票的選中外環以 spring 在色票間彈跳滑動，並聯動上方商品預覽色塊交叉淡入；尺寸格缺貨時以斜線劃過且不可選；選中組合低於庫存門檻時彈出「僅剩 N 件」提示。

載入預覽⋯

Playground

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

預設顏色defaultColor

預設尺寸defaultSize

低庫存門檻lowStockThreshold

顯示商品預覽showPreview

<VariantSwatchPicker />

安裝

npx shadcn@latest add https://webberui.com/r/variant-swatch-picker.json

或在 components.json 設定 registries 後，改用 @webberui/variant-swatch-picker 安裝。

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

npm install motion lucide-react clsx tailwind-merge

使用

import { VariantSwatchPicker } from "@/components/ui/variant-swatch-picker";

<VariantSwatchPicker
  colors={[
    { name: "石墨黑", value: "#26262b" },
    { name: "燕麥白", value: "#ece5d8", light: true },
  ]}
  sizes={["S", "M", "L"]}
  stock={{
    石墨黑: { S: 12, M: 8, L: 0 },
    燕麥白: { S: 0, M: 4, L: 15 },
  }}
  defaultColor="石墨黑"
  onChange={({ color, size, stock }) => console.log(color, size, stock)}
/>

Props

Prop	型別	預設值	說明
`colors`	`SwatchColor[]`	—	可選的顏色色票清單（`{ name, value, light? }`），`value` 支援漸層字串
`sizes`	`string[]`	—	可選的尺寸清單
`stock`	`Record<string, Record<string, number>>`	—	庫存表 `stock[顏色][尺寸] = 件數`，未列出的組合視為缺貨
`lowStockThreshold`	`number`	`5`	低庫存門檻，選中組合庫存小於等於此值時顯示「僅剩 N 件」
`defaultColor`	`string`	第一個有庫存的顏色	預設選中的顏色名稱
`defaultSize`	`string`	—	預設選中的尺寸，該組合缺貨時視為未選
`showPreview`	`boolean`	`true`	是否顯示上方的商品預覽色塊
`onChange`	`(selection) => void`	—	選擇變更回呼，帶 `{ color, size, stock }`，`size` 為 `null` 表示尚未選尺寸
`className`	`string`	—	透傳到最外層容器

可及性

顏色與尺寸各為 role="radiogroup"，選項為 role="radio" 並帶 aria-checked 狀態
缺貨的顏色與尺寸設為 disabled，且 aria-label 標註「（缺貨）」供輔助科技朗讀
庫存提示區塊帶 aria-live="polite"，庫存變化時會被朗讀且高度固定不造成版面跳動
使用者系統開啟「減少動態效果」時，外環與底色直接定位、預覽色塊瞬時切換，不播放 spring 動畫
所有選項皆可鍵盤操作，並帶清晰的 focus-visible 焦點環

規格色票選擇器

Playground

安裝

使用

Props

可及性

On this page