VariantSelector

A flexible variant selector that supports both single and multiple selection modes. Renders card-style items that can display images or colours. Single mode is a Base UI RadioGroup and multiple mode a Base UI ToggleGroup, so either way the set is one tab stop and the arrow keys move between items.

Sand

Ash

Terracotta

Smoked oak

Usage

import { VariantSelector, VariantSelectorItem } from "@instruments/materia-ui/compositions/variant-selector";

Best practices

Fill it with VariantSelectorItem children - they read selection from context; value/defaultValue matches each item's value.
mode is a discriminated prop: "single" renders a role="radiogroup" and gives onValueChange a string, "multiple" renders a <fieldset> of pressed-state toggles and a string[] - keep value/defaultValue types matching the mode.
defaultValue is uncontrolled: the selector tracks later picks itself. Pass value with onValueChange to control it.
Use VariantSelector for image/colour swatch pickers; for a labelled icon-over-text option grid use IconCard, and for plain radio/checkbox lists use RadioGroup/Checkbox.

Props

VariantSelector

Prop	Type	Description
children	`ReactNode`	Child elements
className	`string`	CSS class name
defaultValue	`string \| string[]`	Initial value
mode(required)	`"multiple" \| "single"`	Component mode
onValueChange	`((value: string) => void) \| ((value: string[]) => void)`	Value change handler
value	`string \| string[]`	Current value

VariantSelectorItem

Prop	Type	Description
className	`string`	CSS class name
color	`string`	Colour value
disabled	`boolean`	Whether disabled (blocks interaction)
highlighted	`boolean`	Whether this option is highlighted (compatible with a hovered unavailable option)
image	`ReactNode`
label(required)	`string`	Label text
onMouseEnter	`() => void`	Called when mouse enters this item
onMouseLeave	`() => void`	Called when mouse leaves this item
unavailable	`boolean`	Whether unavailable (visual styling only, still clickable)
value(required)	`string`	Current value

Composition

Builds on

Flex, Swatch

Used by

ProductSpecificationsSelector