# VariantPicker Part of the Dovetail design system (https://graham-goebel.github.io/Dovetail/), in the Commerce family. Files: [VariantPicker.jsx](https://graham-goebel.github.io/Dovetail/system/components/commerce/VariantPicker.jsx), [VariantPicker.d.ts](https://graham-goebel.github.io/Dovetail/system/components/commerce/VariantPicker.d.ts), [VariantPicker.md](https://graham-goebel.github.io/Dovetail/system/components/commerce/VariantPicker.md). Live page: https://graham-goebel.github.io/Dovetail/components/VariantPicker.html ## Guidelines Choose one variant of a product, such as a size, a colour or a material: a radio group of chips or colour swatches, or the system `Select` for a long list. ### Use it when - A product comes in options and the customer picks one before adding it to the cart. - Some options are out of stock but should stay visible, so people know they exist. - Colours are best shown as colours: `variant="swatches"`. ### Don't use it when - More than one can be chosen, such as toppings or add-ons. Use `CheckboxGroup`. - It is a filter on a product list, which usually allows several values. Use `Tag`s or a `CheckboxGroup`. - The choice is not about a product, such as a plan or a setting. Use `RadioGroup`. ### Example ```jsx const [size, setSize] = React.useState(); ``` ### Variants | Variant | What it is for | |---|---| | `chips` | Default. Labelled buttons at least 44px square, for sizes, materials and anything with a short text label. A `note` shows as a second line. | | `swatches` | 44px circles of each option's `color` or `image`, for colours and fabrics. The chosen one has a ring. The label is the accessible name and a tooltip, and the legend shows it ("Colour: Chalk"). | | `select` | The system `Select`, for a long list (more than about a dozen) or long labels. `showSelected` doesn't apply: the select shows its value. | Unavailable options (`disabled: true`) stay in place. A chip is struck through with a dashed border; a swatch is crossed. `showSelected` (on by default) prints the chosen label after the legend: "Size: M". ### Composition - On a product page, one picker per dimension, stacked under the price and above the quantity and the add button. - Swatch colours come from product data. They are content, not design tokens, so a literal colour value in `options` is right. - `select` renders `Select`, and so `Field` for its label. In that variant, extra props go to the native ` ({ value: o.value, label: o.disabled || o.note ? `${o.label} (${[o.note, o.disabled ? unavailableLabel : null].filter(Boolean).join(", ")})` : o.label }))} onChange={(e) => { /* Select renders options as strings, so an unavailable one can be picked in the native list; it is ignored here and the controlled value snaps back. */ const o = options.find((x) => x.value === e.target.value); if (o && !o.disabled && o.value !== value && onChange) onChange(o.value); }} style={style} {...rest} /> ); } const swatches = variant === "swatches"; const count = options.length; const firstEnabled = options.findIndex((o) => !o.disabled); /* One tab stop: the chosen option, or the first available one. */ const tabStop = selected && !selected.disabled ? selected.value : firstEnabled >= 0 ? options[firstEnabled].value : null; const choose = (o) => { if (!o || o.disabled) return; if (o.value !== value && onChange) onChange(o.value); const el = refs.current[o.value]; if (el) el.focus(); }; /* The next available option from i in direction dir, wrapping. */ const step = (i, dir) => { for (let k = 1; k <= count; k++) { const j = (((i + dir * k) % count) + count) % count; if (!options[j].disabled) return options[j]; } return null; }; const onKeyDown = (e, i) => { const rtl = !!(e.currentTarget.closest && e.currentTarget.closest('[dir="rtl"]')); const fwd = rtl ? "ArrowLeft" : "ArrowRight"; const back = rtl ? "ArrowRight" : "ArrowLeft"; let next = null; if (e.key === fwd || e.key === "ArrowDown") next = step(i, 1); else if (e.key === back || e.key === "ArrowUp") next = step(i, -1); else if (e.key === "Home") next = step(-1, 1); else if (e.key === "End") next = step(count, -1); else return; e.preventDefault(); choose(next); }; const option = (o, i) => { const checked = o.value === value; const off = !!o.disabled; const hovered = hover === o.value && !off && !checked; const common = { ref: (el) => { refs.current[o.value] = el; }, type: "button", role: "radio", "aria-checked": checked, "aria-disabled": off || undefined, "aria-label": nameOf(o), tabIndex: o.value === tabStop ? 0 : -1, onClick: () => choose(o), onKeyDown: (e) => onKeyDown(e, i), onMouseEnter: () => setHover(o.value), onMouseLeave: () => setHover(null), }; if (swatches) { return ( ); } return ( ); }; return (
{label} {showSelected && selected && ( )}
{options.map(option)}
); } ```