電商購物體驗
規格色票選擇器
顏色色票與尺寸選擇器，缺貨斜線、選中彈跳與庫存提示。
電商商品頁的規格選擇器：顏色色票的選中外環以 spring 在色票間彈跳滑動，並聯動上方商品預覽色塊交叉淡入；尺寸格缺貨時以斜線劃過且不可選；選中組合低於庫存門檻時彈出「僅剩 N 件」提示。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add variant-swatch-pickerPlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
5
編輯中的呼叫預設屬性
<VariantSwatchPicker/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/variant-swatch-picker.json或在 components.json 設定 registries 後，改用 @webberui/variant-swatch-picker 安裝。
使用
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焦點環