Color Swatch

Use ColorSwatch to display a selectable color option, such as one of a product’s available colors. It renders a radio input by default, or a checkbox when you set multi.

Import

import { ColorSwatch } from '/@dropins/tools/components.js';

Props

Prop	Type	Req?	Description
label	string	No	Field label.
groupAriaLabel	string	No	Label for the swatch group, used in the accessible label.
name	string	No	Field name, used to map the value in a form.
id	string	No	Field id.
value	string	No	Field value.
color	string	No	Color of the swatch. Accepts any valid CSS color; falls back to a default gray when invalid.
size	'medium' | 'large'	No	Size of the color swatch. Defaults to medium.
selected	boolean	No	Whether the color swatch is selected. Defaults to false.
disabled	boolean	No	Whether the color swatch is disabled. Defaults to false.
outOfStock	boolean	No	Whether the color swatch is out of stock. Defaults to false.
multi	boolean	No	Whether the swatch allows multiple selection, rendering a checkbox instead of a radio. Defaults to false.
onValue	(value: any) => void	No	Function to handle value changes.
onUpdateError	(error: Error) => void	No	Function to handle errors thrown by onValue.

ColorSwatch also accepts standard input HTML attributes (for example, aria-describedby and className), except label and size. Don’t pass your own onChange — it replaces the component’s built-in value handling; use onValue instead.

Example

Render a selectable color swatch and handle selection with onValue:

import { ColorSwatch, provider } from '/@dropins/tools/components.js';

await provider.render(ColorSwatch, {
  name: 'color',
  label: 'Gray',
  groupAriaLabel: 'Color',
  value: 'gray',
  color: '#E8E8E8',
  selected: false,
  onValue: (value) => yourSelectColor(value),
})(document.querySelector('.colorswatch'));

Related

• Image Swatch — the same selection pattern for image-based options.
• Design tokens — the colors, spacing, and sizing swatches use.