SwatchSelector

Row of selectable color/image swatches with controlled single selection, built on Base UI ToggleGroup: the row is one tab stop and the arrow keys move between swatches. Shares the selected value, onValueChange, and size with its {@link SwatchSelectorItem} children through context.

Usage

import { Swatch, SwatchMore, SwatchSelector, SwatchSelectorItem } from "@instruments/materia-ui/components/swatch-selector";

Best practices

Pair SwatchSelector with SwatchSelectorItem children - it shares value/onValueChange/size through context, so items need no individual wiring.
Prefer SwatchGroup when the row is a single-choice form control needing radio roles and form submission; SwatchSelector is a row of pressed-state toggle buttons.
Pressing the selected swatch again keeps it selected and does not call onValueChange.
Selection is controlled - pass value and update it from onValueChange; there is no internal fallback state to fall back on.

Props

Swatch

Prop	Type	Description
color	`string`	CSS colour value (hex, rgb, hsl, etc.). If provided along with children, children render on top.
aria-label	`string`	Defines a string value that labels the current element. Accessible label for screen readers.
value(required)	`string`	Unique value for this swatch
children	`import("react").ReactNode`	Custom content rendered inside the swatch (e.g., images).
size	`SwatchSize`	Override size for this specific swatch.
unavailable	`boolean`	Whether this option is unavailable (out of stock)

SwatchMore

Prop	Type	Default	Description
count(required)	`number`		Number of additional swatches not shown; rendered as `+{count}`.

SwatchSelector

Prop	Type	Description
value	`string`	Value of the currently selected item (controlled single selection).
onValueChange	`(value: string) => void`	Fired with the newly selected item's `value` when a swatch is clicked.
size	`SwatchSize`	Swatch size, inherited by items via context unless they override it.

SwatchSelectorItem

Prop	Type	Description
color	`string`	CSS colour value (hex, rgb, hsl, etc.). If provided along with children, children render on top.
aria-label	`string`	Defines a string value that labels the current element. Accessible label for screen readers.
value(required)	`string`	Unique value for this swatch
children	`import("react").ReactNode`	Custom content rendered inside the swatch (e.g., images).
size	`SwatchSize`	Override size for this specific swatch.
unavailable	`boolean`	Whether this option is unavailable (out of stock)

Composition

Builds on

Swatch, Tooltip

Used by

ProductCard