ColorPicker

A colour swatch that grows into a full picker with format switching, eyedropper, saved swatches and a live contrast readout.

When to use

• Theme, brand or label colour settings where people need precise values.
• When contrast against a known surface matters; pass that surface as background.
• Not for picking from a small fixed palette; use RadioCards or a row of buttons.

Usage

import { ColorPicker } from "@/components/iris/color-picker/color-picker";

const [color, setColor] = useState("#2F6BFF");
const [swatches, setSwatches] = useState([
  { id: "wine", color: "#7B2D43" },
  { id: "verdigris", color: "#3E8E7E" },
]);
h(ColorPicker, {
  label: "Accent",
  value: color,
  onValueChange: setColor, // always hex, with alpha digits when not opaque
  background: "#FFFFFF", // the surface the colour will sit on
  swatches,
  onSwatchesChange: setSwatches,
});

Props

Prop	Type	Default	Description
value	string	–	Controlled colour: hex, rgb(), hsl() or oklch().
defaultValue	string	"#2F6BFF"	Uncontrolled starting colour.
onValueChange	(hex: string) => void	–	Receives uppercase hex, with two alpha digits when not opaque.
background	string	"#FFFFFF"	Background for the WCAG contrast readout.
label	string	"Color"	Name shown on the swatch, such as "Accent".
swatches / defaultSwatches	{ id; color }[]	–	Controlled or initial saved swatches.
onSwatchesChange	(swatches) => void	–	Called when swatches are added, reordered or removed.
maxSwatches	number	7	Saving past it drops the oldest.
defaultFormat	"hex" | "rgb" | "hsl" | "oklch"	"hex"	Format shown in the text field first.
className	string	–	Extra class on the root.

Notes

• Keyboard: arrows move the 2D thumb or a focused slider (Shift for x10); PageUp/PageDown and Home/End on sliders; Enter applies typed values (invalid input shakes); Alt+Left/Right reorders a swatch, Delete removes it; Escape discards a draft, then closes.
• The panel is a labelled dialog; the field is a 2D slider plus hue and opacity sliders; swatches are a listbox with roving focus. The contrast ratio and grade are spelled out for screen readers.
• The eyedropper button only renders where window.EyeDropper exists (Chromium desktop).
• Reduced motion swaps the clip-path grow for a fade and drops thumb springs and the format morph.
• Theme: the trigger and panel use surface, line (line-strong on hover and with prefers-contrast: more) and rounded-panel (the trigger and its buttons use rounded-button); the contrast grade uses green, orange and red; an invalid typed value turns the field border red.
• The panel opens over the trigger and grows from its top left corner, so leave room below and to the right.