Color Picker

Anatomy

ColorPicker holds the colour; the parts read and write it. You compose only the parts you need — a hex field has no use for the opacity slider — in any layout. By default the content opens in a popover from ColorPickerTrigger; with inline it is drawn in place.

import {
  ColorPicker, ColorPickerTrigger, ColorPickerSwatch, ColorPickerContent, ColorPickerArea,
  ColorPickerHueSlider, ColorPickerAlphaSlider, ColorPickerEyeDropper,
  ColorPickerFormatSelect, ColorPickerInput,
} from '@comitor/ui'

<ColorPicker                     // a <div> holding the store; the popover root unless inline
  value={value}                  // or defaultValue — '#000000' when neither is given
  onValueChange={setValue}       // emits in the current format: '#1e66f5', 'rgb(30, 102, 245)'…
  defaultFormat="hex"            // 'hex' | 'rgb' | 'hsl' | 'hsb'
  name="background"              // inside a <form>: a hidden input posts '#rrggbb'
  inline={false}                 // true draws the content in place, no popover and no trigger
>
  <ColorPickerTrigger>           // Button variant="outline" that opens the popover
    <ColorPickerSwatch />        // role="img", named "Current color: #…" — names the trigger
  </ColorPickerTrigger>
  <ColorPickerContent>           // PopoverContent (or a plain <div> when inline), 340px wide
    <ColorPickerArea />          // saturation × brightness, a keyboard 2-D slider
    <ColorPickerHueSlider />     // 0–360°
    <ColorPickerAlphaSlider />   // 0–100% — leave it out when you store hex
    <ColorPickerEyeDropper />    // renders nothing outside Chromium
    <ColorPickerFormatSelect />  // HEX / RGB / HSL / HSB
    <ColorPickerInput />         // the typed value, one box per channel
  </ColorPickerContent>
</ColorPicker>

Basic usage

Controlled with value and onValueChange. The trigger is the package’s outline Button; the ColorPickerSwatch inside it is an image named “Current color: #1e66f5”, and aria-labelledby joins that to the field title so the button is announced as “Brand colour, Current color: #1e66f5”. The value is stored as hex, so this picker has no opacity slider and its input is withoutAlpha. Drag across the area: the counter moves once per colour that actually changed, not once per pointer event.

The pipette button is ColorPickerEyeDropper. It uses the browser’s EyeDropper API, which only Chromium browsers have — in Safari and Firefox the part renders nothing and the layout closes around it. It also renders nothing on the server and during hydration, and appears right after, so do not build a layout that depends on its width.

Inline, with opacity

inline renders ColorPickerContent as a plain <div> where you put it — for a side panel or a settings card where a popover would be one click too many. There is no trigger; style the root yourself (a border here). This one shows every part, opacity included, in rgb format. The readout under the inputs is not a part of the package: it is four calls to useColorPicker, which reads the picker’s store from inside it.

useColorPicker takes a selector and re-renders when its result changes. Select primitives, as above. The store mutates its state object in place, so useColorPicker((s) => s) never re-renders, and a selector that builds a new object on every call — (s) => ({ h: s.hsv.h }) — makes React loop. Outside a ColorPicker it throws; for anything outside, use onValueChange.

Keyboard on the area

The area’s thumb is a focusable two-axis slider. Tab to it in the inline demo above, or click the area — a press moves focus to the thumb, so the keys carry on from where you clicked.

Everything is clamped to 0–100. The horizontal keys do not swap under dir="rtl": the area’s gradient does not mirror either, so the keys follow what is drawn. Hue and opacity are ordinary Radix sliders — arrows by 1, PageUp / PageDown by 10, Home / End to the ends.

Formats and controlled value

onValueChange writes the colour in the current format — #1e66f5, rgb(30, 102, 245), hsl(220, 91%, 54%), hsb(220, 88%, 96%), with rgba / hsla / hsba when opacity is under 100% — and value reads any of them back, so a controlled picker works in every format. ColorPickerFormatSelect switches the format; onFormatChange tells you. Try the buttons, then the select, then drag.

Three things the log shows. Switching the format fires onFormatChange but not onValueChange: your state keeps the old string until the colour next changes. Setting a value from outside does not echo back through onValueChange. And format is not a controlled prop — it is read once, like defaultFormat; to force a format from outside, remount the picker with a key. If what you store is hex, keep the format at hex or read the posted field below, which is hex whatever the picker shows.

In a form

Give the root a name and a hidden <input> joins the nearest ancestor <form>. Its value is always #rrggbb — lower case, no alpha — even when the picker shows RGB, as the background field below does. readOnly keeps the brand colour focusable and inspectable but unchangeable, and it still posts; disabled takes the accent out of the tab order and out of FormData.

There is no empty state: a picker always holds a colour (#000000 when you give none), so an optional colour field needs its own “no colour” switch next to it. And required goes only to the hidden input, which browsers leave out of constraint validation — check what you need in the submit handler.

The trigger

ColorPickerTrigger is an outline Button — pass variant to change it. Put the swatch inside it. Dice UI’s examples put it the other way round, with asChild turning the swatch itself into the trigger; the swatch is a <div role="img">, so the result opens on a click and can never be reached with Tab. Use asChild only onto something that is focusable on its own, such as a <button>.

// ✓ The swatch INSIDE the default trigger: a real <button>, reachable with Tab, named by the swatch.
<ColorPickerTrigger>
  <ColorPickerSwatch />
</ColorPickerTrigger>

// ✓ asChild onto an element that is focusable on its own.
<ColorPickerTrigger asChild>
  <button type="button" className="…">Pick a colour</button>
</ColorPickerTrigger>

// ✗ Upstream's pattern. The swatch is a <div role="img">: a mouse can click it, Tab never reaches it.
<ColorPickerTrigger asChild>
  <ColorPickerSwatch />
</ColorPickerTrigger>

Language

Nothing in the picker is visible text except the format names. Its strings are accessible names and value texts — the area, the sliders, each channel box, the swatch, the eyedropper, the format select — in the colorPicker namespace. The ones with a number inside are functions: areaValueText(saturation, brightness), hueValueText(degrees), alphaValueText(percent), swatchLabel(color). The channel names are deliberately long (“Red color component (0-255)”) because nothing visible stands next to those boxes. Switch the language and read the names back:

The labels prop beats the nearest ComitorLocaleProvider, which beats English. The field’s own title is your string. Where the provider goes: Get started → Set the language.

Props

ColorPicker — every other prop goes to the root <div>.

The parts. Each one throws outside a ColorPicker, and each sets its own data-slot (color-picker-area, color-picker-input…) for styling.

The hook. Prefer onValueChange for anything outside the picker; the hook is for what renders inside it.

Known limitations

• Hex drops alpha. The hex format and the hidden form input are always #rrggbb; moving the opacity in hex format changes the swatch but fires no onValueChange. If you store hex, leave out ColorPickerAlphaSlider and pass withoutAlpha.
• format is not controlled. It seeds the picker once; later changes of the prop are ignored. Changing the format also fires no onValueChange.
• Unreadable values turn black. value understands only what the picker itself emits, with whole-number channels. A named colour, 8-digit hex, oklch() or hsl(210.5, …) is drawn as black without a warning — normalise stored values to hex.
• Controlled means echoed, not enforced. The picker updates its own state before it calls onValueChange, so a parent that ignores the call does not undo the change. To stop changes, use readOnly or disabled.
• No empty value, and no validation. The picker always holds a colour, and required cannot block a submit. Only an ancestor <form> counts — a picker tied to a form elsewhere through the form attribute posts nothing.
• The eyedropper is Chromium-only, and appears only after hydration.
• Right-to-left is partial. The hue and opacity gradients do not mirror while Radix mirrors their thumbs, as upstream; the area never mirrors.
• ColorPickerTrigger asChild onto the swatch is mouse-only. Keep the swatch inside the default trigger.

Accessibility

• The area thumb is role="slider" with aria-roledescription, aria-valuenow for saturation and an aria-valuetext that reads both axes (“Saturation 64%, brightness 96%”). Pass aria-label or aria-labelledby on ColorPickerArea to rename it; both go to the thumb. The same holds for the two sliders.
• Name the trigger after the field. On its own it is announced as “Current color: #…” from the swatch inside; point aria-labelledby at the field title and the swatch, as the demos do, so it says what the colour is for.
• The swatch is role="img" named with the colour in the current format, and keeps its colour under Windows High Contrast (forced-color-adjust: none).
• readOnly keeps every part focusable and adds aria-readonly to the three thumbs; disabled takes them out of the tab order and sets aria-disabled on the area thumb.
• Focus on the thumbs is a 2px outline-ring outline with a 2px offset; the two-tone ring around each thumb keeps it visible on any colour.
• The colour itself is not text-contrast-checked and cannot be: it is the user’s data. Show its code next to the swatch wherever the exact value matters, so nobody has to judge it by eye.

Related

• Color Swatch — display a stored colour in a table or on a detail page.
• Colors — the tones to use for labels, projects and statuses instead of a free colour.
• Popover — what the content opens in, and where open, onOpenChange and modal come from.
• Slider — the plain range control the hue and opacity sliders are built on.
• Field — titles, descriptions and errors around a picker in a form.