Variant Swatches React component
Product option pickers for colour and size: round colour swatches with a ring that glides to the pick, size chips with a sliding fill, the chosen value named in the label, sold-out options struck through, and a low-stock warning when only a few are left.
About the Variant Swatches component
Variant Swatches is a product option picker: round color swatches for colors and text chips for sizes or any other option. The selected swatch gets a ring and the selected chip a fill that slide between options, the group heading shows the picked name (Color · Sand), hovering a color shows its name in a tooltip, and a warning like "Only 3 left" appears when stock runs low.
groups takes a list of option groups, each with a name, a type (color or size) and options with value, label and optional color, soldOut and stock. Sold-out colors are struck through diagonally and sold-out chips crossed out; both stay visible but cannot be picked. value or defaultValue holds the choice per group name, like { Color: "black", Size: "s" }, and onValueChange reports it. lowStock sets the warning threshold (3 by default) and size picks sm, md or lg.
When to use it
Use Variant Swatches on product pages and quick-add dialogs wherever shoppers pick a colour, size or other option. Seeing sold-out and low-stock options up front saves a disappointed add-to-cart.
Keep the option names short (they appear in the label and tooltip) and update the product image when the colour changes.
Installation
Add the Variant Swatches component to your project with the shadcn CLI. It lands in components/variant-swatches.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/variant-swatchesOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<VariantSwatches /> accepts 8 props, all optional.
| Prop | Type | Default |
|---|---|---|
| groups | { name: string; type: "color" | "size"; options: SwatchOption[] }[] | DEFAULT_GROUPS |
| value Selected value per group name. | Record<string, string> | — |
| defaultValue | Record<string, string> | { Color: "black", Size: "s" } |
| onValueChange | (value: Record<string, string>) => void | — |
| lowStock Show "Only n left" when stock is at or below this. | number | 3 |
| size | "sm" | "md" | "lg" | "md" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- groups{ name: string; type: "color" | "size"; options: SwatchOption[] }[]Default: DEFAULT_GROUPS
- value
Selected value per group name.
Record<string, string> - defaultValueRecord<string, string>Default: { Color: "black", Size: "s" }
- onValueChange(value: Record<string, string>) => void
- lowStock
Show "Only n left" when stock is at or below this.
numberDefault: 3 - size"sm" | "md" | "lg"Default: "md"
- theme"dark" | "light"Default: "dark"
- classNamestring
Collections
Use-case pages that compare Variant Swatches with the other components that do a similar job.
npm dependencies
Installed for you by the shadcn CLI.
Variant Swatches FAQ
- How are sold-out options shown?
- Colour swatches fade with a diagonal strike and size chips get struck through; both stay visible but can't be selected, and screen readers hear 'sold out'.
- When does the low-stock warning appear?
- When the selected option's stock is at or below lowStock (3 by default). Size chips with low stock also carry a small dot.
- Can I add more option types?
- Add as many groups as you need; use type size for any text options (material, length, pack size).
- Is it keyboard accessible?
- Each group is a radio group. Tab reaches the selected option, and the arrow keys move to the next option that is not sold out, skipping sold-out ones.
