# Variant Picker

> Product options as accessible radio groups: color swatches (solid or two-tone), a size grid with a gliding highlight, pills with a note line and image tiles. Hovering previews a value's name in the legend, stockOf strikes through sold-out values (still pickable for a notify-me flow) and dots low ones, and a status line reports stock for the full selection.

- Slug: `variant-picker`
- Category: [Commerce](https://www.assembli.design/category/commerce.md)
- Type: component
- Tags: variants, swatches, size-picker, product-options, ecommerce, stock, radio-group
- npm dependencies: motion
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/variant-picker
- Page: https://www.assembli.design/components/variant-picker

![Variant Picker preview](https://www.assembli.design/thumbnails/variant-picker-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `VariantOption[]` |  |  |
| `value` | `VariantSelection` |  |  |
| `defaultValue` | `VariantSelection` |  |  |
| `onValueChange` | `(selection: VariantSelection, changed: string) => void` |  |  |
| `stockOf` | `(selection: VariantSelection) => number \| undefined` |  | Units in stock for a full selection, or `undefined` when unknown (treated as in stock). The picker also asks about each value with the rest of the selection held, to mark sold-out and low-stock value… |
| `lowStockAt` | `number` | `3` | At or below this many units a value gets a dot and the status reads "Only n left". |
| `shipping` | `React.ReactNode` |  | Shown beside "In stock". |
| `hideStatus` | `boolean` |  | Hides the stock line under the options. |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/variant-picker/variant-picker.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/variant-picker
```

Registry item JSON: https://www.assembli.design/r/variant-picker.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.