elements
Manual UI Templates ColorPicker

ColorPicker

elements man ui/templates/color-picker

Pick a color with an area, channel sliders, inputs, swatches and the eye dropper.

Example
import { ColorPicker } from "@elements/ui/color-picker";

<ColorPicker value={theme.accent} attrs={{ "aria-label": "Accent color" }} />
<ColorPicker value={brush.color} inline swatches={["#ef4444", "#22c55e", "#3b82f6"]} />

Parts

Part What it is
.color-picker The root; --value holds the color.
.color-picker-control The hex input and trigger.
.color-picker-trigger Opens the panel; shows the color.
.color-picker-content The panel, in the popover or inline.
.color-picker-area Saturation by brightness.
.color-picker-area-thumb The area's thumb, role=slider.
.color-picker-slider A channel slider (data-channel, data-orientation).
.color-picker-slider-label The slider's channel letter (sliderLabels).
.color-picker-slider-value The slider's value (sliderLabels).
.color-picker-value-text The color as text (valueText).
.color-picker-channels Hex and channel inputs.
.color-picker-format The format select.
.color-picker-format-trigger The format trigger button (formatTrigger).
.color-picker-swatches Preset swatches.
.color-picker-grid The transparency checkerboard.

Attributes

Attribute Type Default Description
value string (two-way) "#000000" The color as a CSS string. Hex, rgb(a), hsl(a), hsb(a) or a named color goes in. A value that is not a color shows as typed.
valueFormat "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba" "hex" How value is written. hex adds alpha only below 1.
format "rgba" | "hsla" | "hsba" (two-way) "rgba" Which channel inputs show, and which saturation a saturation slider edits.
open boolean (two-way) false The popover is open.
inline boolean false Shows the panel in the page instead of a popover.
trigger boolean true false leaves only the control: a value swatch, the hex input and the eye dropper, with no panel.
area boolean true Shows the saturation and brightness area.
xChannel ColorChannel "saturation" The channel the area runs along x: hue, saturation, brightness, lightness, red, green or blue.
yChannel ColorChannel "brightness" The channel the area runs along y, min at the bottom.
sliders ColorChannel[] | null null The channel sliders, any of hue, saturation, lightness, brightness, red, green, blue and alpha. null is hue and alpha; [] is none.
orientation "horizontal" | "vertical" "horizontal" Lays the channel sliders out across or standing up.
sliderLabels boolean false Shows each slider's channel letter and value.
valueText boolean false Shows the color as text, with a swatch.
valueTextFormat ColorStringFormat | "" "" The value text's format; empty uses valueFormat.
alpha boolean true Shows the alpha slider and input.
eyeDropper boolean true Shows the eye dropper (disabled where the browser has none).
channelInputs boolean true Shows the hex and channel inputs.
formatSelect boolean true Shows the format select.
formatTrigger boolean false Shows a button that steps the format through rgba, hsla and hsba.
channelOrientation "horizontal" | "vertical" "horizontal" Lays the channel inputs out in a grid, or stacked with each label before its input.
swatchRespectAlpha boolean true false draws the preset swatches without their alpha.
valueSwatchRespectAlpha boolean true false draws the value swatches without their alpha.
gridSize string "" A CSS length for the transparency grid's cells; empty keeps the theme's.
input boolean true Shows the hex input beside the trigger.
swatches string[] [] Preset colors.
disabledSwatches string[] [] Swatches that cannot be picked: dimmed and skipped.
closeOnSelect boolean false Picking a swatch closes the popover.
openAutoFocus boolean true Moves focus to the color area when the popover opens.
initialFocus string "" A selector in the panel to focus when it opens, in place of the area.
side "top" | "right" | "bottom" | "left" "bottom" Popover side.
align "start" | "center" | "end" "start" Popover alignment.
sideOffset number 4 Gap between the control and the popover.
name string "" Submits the value with its form.
form string "" The id of the form the value belongs to.
disabled boolean false Not interactive.
readonly boolean false Shows the color; nothing changes it.
required boolean false The hex input is required.
invalid boolean false Marks the control invalid.
translations Partial<ColorPickerTranslations> {} Labels for the trigger, area, sliders, inputs, eye dropper and swatches.
class string "" Extra classes on the root.
attrs Record<string, string | number | boolean | undefined> {} Attributes for the hex input (inline: the panel): id, aria-label, data-*.
onValueChange (value: string) => void () => {} Every change, during a drag too.
onValueChangeEnd (value: string) => void () => {} When a change is final: drag end, key, input, swatch.
onFormatChange (format: ColorFormat) => void () => {} When the format select or the format trigger changes the format.
onOpenChange (open: boolean) => void () => {} When the popover opens or closes itself.
onPointerDownOutside (e: PointerEvent) => void () => {} A press outside the open popover.
onFocusOutside (e: FocusEvent) => void () => {} Focus left the open popover.

Keyboard

Keys Action
Enter / Space On the trigger, opens the panel.
Arrow keys On the area: saturation and brightness. On a slider: its channel by 1 (degrees, percent or 0 to 255); ArrowUp and ArrowRight raise it. Shift for larger steps.
PageUp / PageDown Larger steps on the area and sliders.
Home / End Minimum and maximum on the area (saturation) and sliders.
Enter Commits a typed hex or channel value; on a swatch, selects it.
ArrowUp / ArrowDown In a channel input, steps it by 1 (Shift 10).
Escape Closes the panel and returns focus to the trigger.

Data attributes

Attribute Values On
data-state "open" | "closed" root, control, trigger
data-state "checked" | "unchecked" swatch trigger, swatch
data-dragging present while dragging root
data-disabled present when disabled (a swatch trigger also when listed in disabledSwatches) root, control, trigger, input, area, area thumb, slider thumb, channel input, eye dropper, value text, swatch trigger
data-readonly present when read-only root, control, trigger, input, area, area thumb, channel input, eye dropper
data-invalid present when invalid root, control, trigger, input, area, area thumb, channel input, eye dropper
data-channel hue, alpha, red, green, blue, saturation, lightness, brightness, hex slider, thumb, channel input
data-value the swatch color swatch trigger, swatch
data-orientation "horizontal" | "vertical" slider, slider track, slider thumb

Accessibility

  • The trigger says the current color and that it opens a dialog; Escape closes it and returns focus.
  • The area thumb is a 2D slider: arrows change saturation and brightness, and its value text says both.
  • Every channel slider is a slider with aria-orientation and value text in degrees, percent or 0 to 255; every channel has a labeled input.
  • Swatches are toggle buttons named by their color.

See also