ColorPicker
Interactive color selection widget with saturation/lightness area, hue and alpha sliders
Category: inputs · WCAG 2.2-AA · color, input, form, picker, hue, alpha
Sizes
- sm
- md
- lg
States
- default
- disabled
Props
| Prop | Type | Default | Description |
|---|---|---|---|
labels | ColorPickerLabels | — | Overrides for the component’s user-visible strings (i18n). |
value | string | — | Controlled hex color value |
defaultValue | string | #3b82f6 | The initial value when uncontrolled. |
onValueChange | (value: string) => void | — | Called with the new value when it changes. |
presets | string[] | — | Preset swatch colors |
alpha | boolean | true | When true, enables alpha (opacity) selection. |
format | 'hex' | 'rgb' | 'hsl' | 'hex' | Notation for the emitted value. Alpha is included whenever alpha is on, so the emitted string has a stable width. |
name | string | — | Submitted with a surrounding form — a hidden input carrying the current value. |
label | string | — | Text label for the control. |
disabled | boolean | false | When true, disables the control and removes it from the tab order. |
size | 'sm' | 'md' | 'lg' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
aria-labelledby | string | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
aria-describedby | string | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
aria-invalid | boolean | — | Wired automatically by a wrapping `Field` when it is in an error state. |
id | string | — | Id for the **focusable control** (not the wrapper), so a `<label for>` names what actually takes focus. `Field` supplies this automatically. |
ariaLabel | string | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. |
Design tokens
--cascivo-color-accent--cascivo-color-surface--cascivo-color-border--cascivo-color-border-strong--cascivo-radius-md--cascivo-radius-full--cascivo-focus-ring
When to use
- Letting a user choose an arbitrary color via a visual saturation/lightness area plus hue control
- Brand or theme customization UIs where an exact color value (hex) is captured
- Forms that need an optional alpha channel alongside the color
When not to use
- Choosing from a small fixed palette only — use a swatch RadioGroup instead
- A single accent toggle where a few preset chips suffice
How to build an accessible ColorPicker in React →
Examples
Basic
<ColorPicker defaultValue="#3b82f6" onValueChange={setColor} />With presets
<ColorPicker presets={["#ef4444", "#3b82f6", "#10b981"]} alpha={false} />