ColorSwatchPicker
color-swatch-pickerChooses a color from a labeled, keyboard-accessible swatch collection.
Usage
Basic usage
Discrete preset color block radio selection, uncontrolled use defaultValue for initial selection.
const PALETTE = ["#ef4444", "#f97316", "#eab308", "#22c55e", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899"];
<ColorSwatchPicker colors={PALETTE} defaultValue="#3b82f6" />Size
size supports sm / md / lg.
<>
<ColorSwatchPicker colors={PALETTE} defaultValue="#22c55e" size="sm" />
<ColorSwatchPicker colors={PALETTE} defaultValue="#22c55e" size="lg" />
</>Theme token palette with readable names
A swatch can be written as { color, label }: the label becomes the accessible name and hover hint, while selection identity stays the color. A token color must carry a label, otherwise a screen reader announces the raw var(--color-primary) string.
var(--color-primary)const TOKENS = [
{ color: "var(--color-primary)", label: "Primary" },
{ color: "var(--color-success)", label: "Success" },
{ color: "var(--color-warning)", label: "Warning" },
{ color: "var(--color-danger)", label: "Danger" },
];
// The emitted value is still the color string, not the label
<ColorSwatchPicker colors={TOKENS} value={v} onValueChange={setV} />Disabled
disabled Reduces the transparency of the entire group and blocks interaction.
<ColorSwatchPicker colors={PALETTE} defaultValue="#8b5cf6" disabled />When to use
Use ColorSwatchPicker to choose one value from a fixed palette, such as brand or label colors. It presents RadioGroup semantics as color swatches and includes arrow-key navigation. Use ColorPicker when the user needs an arbitrary color.
Import
import { ColorSwatchPicker, normalizeSwatches } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| colors* | (string | { color: string; label?: string })[] | - | Preset swatch list. A string is any CSS color (hex / rgb / hsl / named color / var(--color-x)); an object may add a label used as the accessible name and hover hint. Both forms can be mixed |
| value | string | - | Controlled selection value (must be strictly equal to a swatch color) |
| defaultValue | string | - | Uncontrolled initial selection value |
| size | "sm" | "md" | "lg" | "md" | Color block size |
| disabled | boolean | false | Disable entire group |
| className | string | - | Additional class name for the container. |
| aria-label | string | Locale default | Accessible name; enUS provides “Color swatches”, and an explicit value takes precedence. |
ColorSwatchItem (the object form of colors)
| Name | Type | Default | Description |
|---|---|---|---|
| color * | string | - | Any CSS color string. It is also the selection value compared strictly against value. |
| label | string | Falls back to color itself | Accessible name and hover hint. Always provide it for token colors such as var(--color-primary), otherwise a screen reader announces the variable name. |
Events
| Event | Type | Description |
|---|---|---|
| onValueChange | (color: string) => void | Select change callback; the argument is always the swatch color, never the label |
Utilities
| Name | Signature | Description |
|---|---|---|
| normalizeSwatches | (colors: (string | ColorSwatchItem)[]) => { color: string; label: string }[] | Normalizes the mixed array into labelled swatches; string entries and missing or blank labels fall back to the color value itself |
Usage guidelines
- Token colors need a `label`. A bare string in
colorsbecomes the swatcharia-labelverbatim, sovar(--color-primary)is announced as the variable name and means nothing to a screen reader user;#3b82f6andoklch(...)are read as character strings for the same reason. Only named colors such asredortomatosurvive without a label. - Identity for
valueandonValueChangeis always thecolorstring, never thelabel. Do not pass a label back as the selected value. - A controlled
valuemust be strictly equal to a swatchcolorto show as selected."#FFF"differs from"#ffffff", and"#3b82f6"differs from"rgb(59,130,246)"; normalize casing and format before passing values. - The component supports single selection only.
- The default group label follows
ConfigProvider locale; the no-provider fallback remains Chinese.
Related
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
#3b82f6<ColorSwatchPicker colors={PALETTE} defaultValue="#3b82f6" />