Color Picker

Pick a color from a preset palette, from a canvas, or by typing it — and read it back as HEX, RGB, HSL or OKLCH. Every part is opt-in, so the same component covers a nine-swatch brand palette and a full design-tool panel.

Base UI has no color-picker primitive, so this one is built here. It stands on two that do exist: Popover for the anchored surface, and Base UI's Slider for the hue and opacity rails — which is where their keyboard handling, pointer capture and RTL flip come from.

Import

import { ColorPicker } from "@forte-ui/react";

Anatomy

ColorPicker.Root owns the color and renders no element. Everything below it is optional; a picker is whichever parts you render.

<ColorPicker.Root>
  <ColorPicker.Trigger />
  <ColorPicker.HiddenInput />
  <ColorPicker.Popup>
    <ColorPicker.Area />
    <ColorPicker.HueSlider />
    <ColorPicker.AlphaSlider />
    <ColorPicker.Swatches />
    <ColorPicker.Row>
      <ColorPicker.EyeDropper />
      <ColorPicker.Preview />
      <ColorPicker.Format />
      <ColorPicker.Input />
    </ColorPicker.Row>
  </ColorPicker.Popup>
</ColorPicker.Root>

ColorPicker.Popup wraps Popover.Popup and takes all of its props — side, align, sideOffset, initialFocus — so placement is tuned the same way it is on a popover. It draws its own arrow, since its children are the picker's parts rather than popup chrome; pass arrow={false} to drop it.

Swap Trigger and Popup for ColorPicker.Panel and the same picker sits in the page instead.

The value

value and defaultValue are CSS color strings, and what comes back out of onValueChange is a CSS color string in the current format. There is no color object to learn — the parsed forms are handed to you in the change details when you want them.

Accepted on the way in: #hex (3, 4, 6 or 8 digits), rgb(), hsl(), oklch(), oklab() and transparent, in both the legacy comma form and the modern space form. A string that cannot be read is ignored, not thrown on, so a half-typed value in your own state never blanks the picker.

Colors outside the sRGB gamut — oklch(0.7 0.4 30) is a common one — are gamut-mapped, not clipped. Chroma is reduced at constant lightness and hue until the color fits, so the hue you asked for survives; clipping each channel at 0 and 1, which is the one-line version, changes the hue as well and hands back a different color family.

Formats

format picks the notation, out of the four in formats. Switching it rewrites the value, not the color: the same color comes back as #7c3aed, rgb(124 58 237), hsl(262.1 83.3% 57.8%) or oklch(0.5413 0.2466 293.01).

That also fires onValueChange with reason "format-change", so a controlled value never ends up in a notation the panel is no longer showing.

Opacity

Rendering ColorPicker.AlphaSlider is what turns alpha on. There is no prop: the picker omits alpha from every format while the color is fully opaque, so a picker without the rail emits #7c3aed and never #7c3aedff. A defaultValue that already carries alpha keeps it either way.

Examples

Swatches only

ColorPicker.Swatches with no canvas and no rails is a palette picker — the right shape wherever the answer has to stay on brand. It works inside ColorPicker.Popup, inside ColorPicker.Panel, or bare, with neither around it. colors takes any strings value accepts, and columns sets both the grid and the arrow-key stride. Set the prop, not --forte-color-picker-swatch-columns: the component writes that variable inline from columns, so overriding it through style redraws the grid but leaves Up and Down stepping by the old row length.

Bare, the parts go in a layout of your own. Here the palette sits beside a text field in a row that wraps — the shape of a color question in a form. A flex row sizes the grid by its content, so the swatches stay at their size. Alone in a block, the grid stretches to the block's width the way it fills a panel's, and its swatches grow with it; give it a width there.

The colors come from colors; children are not read. That is what lets the group know its own order, which is what the single tab stop and the arrow keys are computed from. To build a row element by element — a "recently used" strip, say — use ColorPicker.Swatch on its own, where each swatch is an independent toggle button.

Controlled

Pass value with onValueChange. onValueCommitted fires once when an interaction ends rather than once per pointer move, which is the one to persist from.

The eyedropper

ColorPicker.EyeDropper samples a color from anywhere on the screen. Where the browser has no EyeDropper API — Firefox, and everything on iOS — it renders nothing at all, which is deliberate: it is a shortcut to a color the rest of the picker can already reach, so its absence costs a user nothing, while a button that opens no eyedropper costs them a click and their confidence in the rest of the panel.

Triggers

The trigger shows a swatch, then its children, then the current color in a visually hidden span — so a trigger with no children is still named, by the value itself.

Give it render to draw it as something else. The built-in trigger styling steps aside, so the rendered component keeps its own look; the swatch, the hidden color announcement and the live color variables stay, which is what still makes it a color trigger. Inside a toolbar that something is a Toolbar.Button, which brings the bar's quiet styling, its size, and a place in its arrow-key order.

In a form

ColorPicker.HiddenInput submits the color under a name.

Disabled

disabled on the root reaches every part through context. Each part is separately disabled rather than the panel taking pointer-events: none, so they stay announced as disabled instead of silently vanishing from the keyboard.

Keyboard

Accessibility

The swatch grid is a radiogroup, not a row of buttons, because that is what it is: a set of mutually exclusive options with at most one current. It brings the whole convention with it — one tab stop for the group, arrow keys between swatches, and selection following focus — so a twenty-four color palette costs a keyboard user one Tab instead of twenty-four.

Two further notes:

• Color is announced, not just shown. ColorPicker.Trigger reads out the current value after its label; ColorPicker.Preview is aria-hidden, since a third announcement of the same color on every drag frame is noise. For anyone who cannot use a canvas at all, ColorPicker.Input is the exact route in and out, and it is why the text field is not optional in practice.
• Under forced colors, the canvas, the rails, the swatches and the previews opt out of substitution (.forte-preserve-color) and take a system-colored hairline as their boundary — because in this one component the color is the content, and substituting it would leave four identical rectangles.

The canvas deliberately does not mirror under RTL: it is a picture of a color space, not a line of text, and the hue on the left of every other color tool should not move because the surrounding paragraph runs the other way. The hue and opacity rails do mirror, because a slider's start follows the writing direction, and the gradients follow them.

Theming

Every measure is a custom property on the panel, so a wider canvas, fatter rails and round swatches are five declarations and no fork. A part used without a panel falls back to the same defaults, and takes a knob set on itself or on any element around it.

Four more custom properties are written inline by the component, because they carry live state rather than theme — and because ColorPicker.Popup is portalled to <body>, where a value declared on an ancestor in the React tree would never reach it:

Read them if you are skinning a part; do not set them.

API reference

ColorPicker.Root

ColorPicker.Trigger

Every other <button> prop passes through unchanged, as do Popover.Trigger's render and nativeButton.

ColorPicker.Popup

Renders Popover.Popup — the portal, the positioner and the surface — with the panel inside it, so its props are drawn from all of them.

ColorPicker.Panel

ColorPicker.Row

ColorPicker.Area

ColorPicker.HueSlider

ColorPicker.AlphaSlider

ColorPicker.Swatches

ColorPicker.Swatch

ColorPicker.Preview

ColorPicker.Value

ColorPicker.Format

ColorPicker.Input

ColorPicker.EyeDropper

ColorPicker.HiddenInput

DEFAULT_SWATCHES

The palette ColorPicker.Swatches falls back to: eight neutrals, eight warm hues and eight cool ones. Exported alongside the component, so an app can extend it rather than restate it.

import { DEFAULT_SWATCHES } from "@forte-ui/react";