Color Picker

Playground

Installation

pnpm add @tessinaui/ui

Usage

import { ColorPicker, ColorPickerPanel, ColorSwatchPicker } from "@tessinaui/ui";

{/* Inline panel */}
<ColorPickerPanel defaultValue="#711DC8" onValueChange={setColor} />

{/* Button-triggered popover (bottom sheet below md) */}
<ColorPicker value={color} onValueChange={setColor} label="Brand color" />

{/* Preset-palette picker — no canvas at all */}
<ColorSwatchPicker items={palette} value={color} onValueChange={setColor} />

value accepts hex (#RRGGBB/#RRGGBBAA) plus rgb(), hsl() and hsb() CSS strings. Named colors ("red") are rejected — parseColorString returns null for them, matching React Aria's contract. Emitted values are always uppercase hex.

Examples

Default

The popover trigger with quick swatches.

Commit vs live changes

onValueChange fires per drag frame; onValueCommit fires once per finished interaction — with the original-vs-current preview bar.

Color models

HEX, RGB, HSL and HSB, controlled via model + onModelChange.

In a form

name submits the hex through a hidden input, label names the trigger and panel, required stars it, and errorMessage swaps in with the error ring.

Read-only and disabled

On color

Mobile sheet

Below md the popup presents as a bottom sheet; resize to see the switch.

Swatch-only picker

ColorSwatchPicker — grid and row layouts, a none tile, check indicators, and one-Tab-stop keyboard navigation.

Progressive disclosure

Presets first; the rainbow tile escalates to the full panel.

Recents and saved swatches

The recent-colors row tracks commits; the "+" tile saves into a consumer-owned palette.

Sliders only

showArea={false} — the compact panel.

Trigger variants

The field-like trigger and the bare triggerMode="swatch" color well.

Libraries

Named swatch groups render in a second tab.

Contrast check

The badge shows the live ratio; the solid boundary marks the target threshold and showBothBoundaries adds the other level dashed.

Controlled trigger

API Reference

ColorPickerPanel

ColorPicker (popover trigger)

Extends the panel's functional props, plus:

ref and forwarded HTML attributes (data-*, handlers) land on the TRIGGER — the persistent element; the panel unmounts while closed.

ColorSwatchPicker

ColorPickerSwatch

Skeletons

ColorPickerSkeleton mirrors the closed trigger (size, rounded, triggerVariant, triggerSize). ColorPickerPanelSkeleton mirrors the open panel (showArea, preview, recents, showAlpha, showEyedropper, showInputs, swatches, libraries, contrast, closeable, dir). ColorSwatchPickerSkeleton mirrors the swatch picker (items, layout, columns, size, rounded).

Types

interface ColorSwatchItem {
  value: string; // "#RRGGBB" | "#RRGGBBAA"
  name?: string; // accessible name
}

interface ColorLibrary {
  name: string; // group heading
  colors: ColorSwatchItem[];
}

interface ContrastCheckOptions {
  against: string;              // comparison color (hex)
  target?: "AA" | "AAA";        // default "AA"
  largeText?: boolean;          // 3.0 / 4.5 thresholds instead of 4.5 / 7.0
  showBothBoundaries?: boolean; // dashed second curve for the other level
}

The color utilities hexToHsva, hsvaToHex, parseColorString, and contrastRatio are also exported for app-side use.

Accessibility

The canvas and rails follow the WAI-ARIA slider pattern (the canvas is a 2D slider announcing both channels through aria-valuetext); swatch sets are roving-tabindex toggle groups — one Tab stop, aria-pressed selection.

Keyboard

• The contrast badge announces its ratio after the value settles (~150ms), never per drag frame.
• readOnly keeps every control focusable and announced with aria-readonly="true".
• The trigger's accessible name leads with label ("Color: #711DC8"), so multiple pickers stay distinguishable.

AT matrix

Accessibility tree (Chromium, computed names/roles/states): verified across every surface — trigger, error state, sheet, sliders, swatch groups, read-only and the contrast announcer. What that pass established:

VoiceOver listening: NOT yet recorded. The tree pass above verifies what is announced, not how it sounds in sequence — only a human (or a scripted VoiceOver session) can confirm that. NVDA and JAWS: UNTESTED — no Windows host exists for this project. Both gaps keep the badge at beta (QA flow §5.6).

Notes

• Anatomy (2026-09-03 redesign) — the SV canvas is a full-width SQUARE (equal travel per pixel on both axes; macOS's NSColorPanel ships the same 1:1), the value inputs are ONE bordered group split by hairline seams (model select · value · opacity, with the % inside the box), the eyedropper is an outlined square beside the rails, and the swatch heading carries the "+ Add" action at its end. The row runs on the input family's own control scale: sm controls in the md panel, xs in the sm panel.
• Value model — external strings in, uppercase hex out; the picker keeps an internal HSVA state so hue survives passing through black, white, and gray. HSB inputs map 1:1 onto that state.
• RTL & color geometry — panel chrome mirrors with dir="rtl"; the canvas and rails deliberately stay LTR (React Aria mirrors them instead — recorded divergence: color geometry is a cross-tool convention).
• Contrast checking — translucent colors are measured as rendered, composited over the comparison color. Boundary curves are recomputed per hue via binary search on the WCAG luminance, which is monotonic in brightness.
• Browser support — the eyedropper uses the native EyeDropper API (Chromium only) and hides itself elsewhere.
• Mobile — the popup becomes a swipe-dismissable bottom sheet below md; inputs and thumbs expand to 44px touch targets on small screens (WCAG 2.5.5).
• Forms — the hidden input lives on the trigger side of the popover variant, so the value submits while the popup is closed.