SwatchPicker

SwatchPicker lets people pick a color (or material) from a grid of swatches.

Made of ColorSwatch (any CSS color; this is data, so HEX is allowed), ImageSwatch (a pattern image) and EmptySwatch (an empty swatch, e.g. "Add color"). The selected swatch has a 2px brand-stroke ring with a background-1 gap inside. Keyboard: arrow keys move focus (flipped in RTL), Enter/Space selects, and Tab enters or leaves the group in one step.

Selected: Sakura pink

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX

// npm install yugen-uiimport { SwatchPicker, ColorSwatch, ImageSwatch, EmptySwatch } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Grid

layout="grid" + columnCount; ↑/↓ move by column, ←/→ in order.

Size & shape

size extra-small 20 · small 24 · medium 28 · large 32px; shape square, rounded, circular.

Image, empty & disabled

ImageSwatch for materials; disabled swatches are skipped by keyboard navigation; EmptySwatch works as an add button.

Usage

Give each swatch an aria-label with a readable color name (“Cherry blossom pink”), not just the HEX code.
Show the name of the selected color nearby, so the choice doesn't rely on color alone.
In the grid layout, group colors of the same family by row or column.

Don't

Don't use SwatchPicker for choices that aren't colors or materials. Use RadioGroup.
Don't show too many swatches (>40). Consider a free color input (input type="color") or a HEX input.

Props

Prop · Type	Default	Description
selectedValue / defaultSelectedValuestring	Default: —	Selected value (controlled / uncontrolled).
onSelectionChange(value: string) => void	Default: —	Called when a new swatch is selected (click, Enter, Space).
layout"row" \| "grid"	Default: "row"	Row (wraps) or grid.
columnCountnumber	Default: —	Number of columns when layout="grid".
size"extra-small" \| "small" \| "medium" \| "large"	Default: "medium"	20 / 24 / 28 / 32px.
shape"square" \| "rounded" \| "circular"	Default: "square"	Swatch shape.
spacing"small" \| "medium"	Default: "medium"	Gap 2 / 4px.
ColorSwatch.color / valuestring	Default: —	CSS color (data) and the value returned on selection.
ImageSwatch.srcstring	Default: —	Pattern image URL.
*.disabled / aria-label / iconboolean / string / ReactNode	Default: —	Disables the swatch, screen reader label, icon over the swatch.

Messages

Text built into the component: labels, aria-labels, screen reader announcements.

English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.

messages.swatchPicker

Key · Type	Default (English)	messagesVi
emptySwatchstring aria-label mặc định của EmptySwatch.	Default (English)`"Empty swatch"`	messagesVi`"Ô trống"`