/// Inputs

ColorPicker

Inline color picker: a saturation/value canvas, hue and optional alpha sliders, a hex/rgb field, and preset swatches.

import { ColorPicker } from "@protocore/pds";

View as Markdown

Basics

The value is a hex string, controllable via value / defaultValue / onValueChange. Drag on the canvas to set saturation and brightness, and on the hue bar to set the hue — or arrow through both with the keyboard.

Selected: #3fcf8e

Alpha

Set alpha to add an alpha slider over a checkerboard; the emitted hex then carries an 8-digit alpha byte (#rrggbbaa).

Overlay: #2a6fdbcc

Presets & rgb

Pass swatches for a constrained, brand-approved palette, and format="rgb" to show the value as an rgb() string in the input row. Pass swatches={[]} to hide the preset row entirely.

When to use it

Use ColorPicker for a full, always-visible color-editing surface — inside a settings panel or a theme editor where the picker lives on the page. When space is tight and the picker should open on demand from a field, use ColorInput, which wraps this same picker in a popover. The color math is hand-rolled (HSV ↔ RGB ↔ hex, no libraries); hue is preserved across greyscale colors so dragging value to zero and back doesn't lose your hue.

Usage

Show the resulting value in nearby text — the canvas is not a precise readout.
Constrain the palette with `swatches` when only brand colors are valid.
Enable `alpha` only when transparency applies to the target.
Give the picker an `aria-label` describing what it colors.

Don't

Don't use it for a single on-demand field — use ColorInput's popover.
Don't leave alpha on when the consumer can't render transparency.
Don't assume the emitted hex is 6 digits when `alpha` is set — it's 8.
Don't treat the canvas position as the value; surface the hex.

Accessibility

Keys	Action
`Tab`	Move between the saturation/value canvas, hue, and alpha sliders.
`Arrow keys`	On the canvas: Left/Right adjust saturation, Up/Down adjust brightness. On a slider: adjust its value.
`Shift + Arrow`	Move by a larger (×10) increment.
`Home / End`	Jump the focused control to its minimum / maximum.
`Page Up / Page Down`	Move brightness by a larger increment on the canvas.

The saturation/value canvas and each slider expose `role="slider"` with `aria-valuemin`/`max`/`now` and a descriptive `aria-valuetext`.
The hex/rgb input accepts typed values and commits any valid color immediately.
The gradient canvas is a direction-neutral paint surface — it is not mirrored under RTL, while the surrounding layout is.

`ColorPicker` props

Prop	Type	Default	Description
`alpha`	`boolean`	`false`	Show the alpha slider; the emitted hex then carries an 8-digit alpha byte.
`aria-label`	`string`	`Color picker`	Accessible name for the whole picker group.
`className`	`string`	—	Merged after the pds class on the root.
`defaultValue`	`string`	`#3fcf8e`	Initial color in uncontrolled mode.
`format`	`enum`	`hex`	Text-field format for the input row: `hex` (default) or `rgb`.
`id`	`string`	—	Root id.
`onValueChange`	`((hex: string) => void)`	—	Fires with the next hex string on every change.
`size`	`enum`	`md`	Canvas size: `sm` · `md` (default) · `lg`.
`style`	`CSSProperties`	—	Inline style on the root.
`swatches`	`string[]`	`[ "#3fcf8e", "#2a6fdb", "#e8533f", "#c9a227", "#a855f7", "#8b8b8b", "#fafafa", "#0a0a0a", ]`	Preset swatches. Pass `[]` to hide the row.
`value`	`string`	—	Controlled color as a hex string (`#rrggbb`, or `#rrggbbaa` when `alpha`).