Color Picker

Choose a color by dragging across an area and along sliders, typing any CSS color, or picking a preset.

Use a color picker to choose a color, like a brand or theme color. The value is a CSS color string, and every part edits it: an area for two channels at once, a slider per channel, a text input that reads any CSS color, and presets.

import "@ui-sdk/web/color-picker"
import { formatColor, parseColor, type ColorFormat } from "@ui-sdk/web"
import { createElement, Pipette } from "lucide"

const formats: { label: string; value: ColorFormat }[] = [
  { label: "Hex", value: "hex" },
  { label: "RGB", value: "srgb" },
  { label: "HSL", value: "hsl" },
  { label: "OKLCH", value: "oklch" },
]

const presets = [
  "#ef4444",
  "#f97316",
  "#eab308",
  "#22c55e",
  "#0ea5e9",
  "#6366f1",
  "#a855f7",
  "#ec4899",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-color-picker aria-label="Brand color" format="hex" default-value="#0ea5e9">
      <ui-color-picker-area>
        <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
      </ui-color-picker-area>
      <div data-slot="row">
        <ui-color-picker-eye-dropper>
          <button aria-label="Pick from screen">${createElement(Pipette, { "aria-hidden": "true" }).outerHTML}</button>
        </ui-color-picker-eye-dropper>
        <div data-slot="color-picker-sliders">
          <ui-color-picker-slider channel="hue">
            <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
          </ui-color-picker-slider>
          <ui-color-picker-slider channel="alpha">
            <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
          </ui-color-picker-slider>
        </div>
        <ui-color-picker-swatch></ui-color-picker-swatch>
      </div>
      <div data-slot="row">
        <select aria-label="Format">
          ${formats.map((option) => `<option value="${option.value}">${option.label}</option>`).join("")}
        </select>
        <ui-color-picker-input>
          <input aria-label="Color" />
        </ui-color-picker-input>
      </div>
      <ui-color-picker-swatches aria-label="Presets">
        ${presets.map((preset) => `<ui-color-picker-swatch-item value="${preset}"></ui-color-picker-swatch-item>`).join("")}
      </ui-color-picker-swatches>
    </ui-color-picker>
  `
  const picker = root.querySelector("ui-color-picker")!
  root.querySelector("select")!.addEventListener("change", (event) => {
    const format = (event.currentTarget as HTMLSelectElement)
      .value as ColorFormat
    picker.setAttribute("format", format)
    picker.value = formatColor(parseColor(picker.value)!, format)
  })
}

export { mount }

Drag across the area or along the sliders, or choose a preset. Choose HSL to write the color another way, or type one like rebeccapurple and press Enter.

Installation

npm install @ui-sdk/web @ui-sdk/core

Import the component to register its elements. The import is safe on the server.

import "@ui-sdk/web/color-picker"

Composition

Use the following composition to build a ui-color-picker:

ui-color-picker
├── ui-color-picker-area
│   ├── ui-color-picker-area-canvas
│   └── ui-color-picker-area-thumb
├── ui-color-picker-slider
│   └── ui-color-picker-slider-thumb
├── ui-color-picker-slider
│   └── ui-color-picker-slider-thumb
├── ui-color-picker-swatch
├── ui-color-picker-input
├── ui-color-picker-channel-input
├── ui-color-picker-eye-dropper
└── ui-color-picker-swatches
    ├── ui-color-picker-swatch-item
    └── ui-color-picker-swatch-item

Every part is optional, so use the ones your picker needs.

ui-color-picker holds the value and is a group around the parts.
ui-color-picker-area edits two channels, like saturation across and brightness up. A press moves the thumb there and starts a drag. Its background is --color-area-background, so give it a size and that background.
ui-color-picker-area-canvas paints the area pixel by pixel, for channels no gradient can draw, like OKLCH's chroma and lightness.
ui-color-picker-area-thumb shows where the color sits in the area. It's a slider that screen readers hear as both channels.
ui-color-picker-slider edits one channel, like hue or alpha, drawn by --color-slider-background.
ui-color-picker-slider-thumb shows where the channel sits along its slider.
ui-color-picker-swatch shows the color, named for screen readers, like "vivid blue".
ui-color-picker-input wraps an <input>, which reads any CSS color when you press Enter or leave it. Text that isn't a color goes back to the value.
ui-color-picker-channel-input edits one channel as a number, in the units people read it in, like 0 to 255 for red.
ui-color-picker-eye-dropper picks a color from anywhere on the screen, where the browser can.
ui-color-picker-swatches and ui-color-picker-swatch-item are a list of preset colors.

Each part writes the color as --color-picker-color, so a thumb or a swatch fills itself with background: var(--color-picker-color). The picker is form-associated, so it submits its value like a native input. The inputs, the canvas, the eye dropper and preset items use the <input>, <canvas> or <button> you put inside them, or make one.

Usage

Import the parts and put them together:

<script type="module">
  import "@ui-sdk/web/color-picker"
</script>

<ui-color-picker aria-label="Brand color" default-value="#0ea5e9">
  <ui-color-picker-area>
    <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
  </ui-color-picker-area>
  <ui-color-picker-slider channel="hue">
    <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
  </ui-color-picker-slider>
  <ui-color-picker-input>
    <input aria-label="Hex" />
  </ui-color-picker-input>
</ui-color-picker>

Name the picker with aria-label, or put it in a Field whose label names it. Without default-value, it starts at black.

Spaces and Channels

space decides which channels the parts edit, and what the value is written in:

`space`	Area, across and up	Slider	Value written as
`hsv`	saturation, brightness	hue	hex, like `#0ea5e9`
`hsl`	saturation, lightness	hue	`hsl(198.63 88.66% 48.43%)`
`srgb`	red, green	blue	`rgb(14 165 233)`
`oklch`	chroma, lightness	hue	`oklch(0.6847 0.1479 237.32)`

Set format to write the value another way, like format="hex" in any space. Every space has an alpha channel too. Set x and y on the area, or channel on a slider, to edit other channels:

<ui-color-picker
  aria-label="Background"
  space="hsl"
  default-value="hsl(220 60% 50%)"
>
  <ui-color-picker-area x="hue" y="lightness">
    <ui-color-picker-area-canvas></ui-color-picker-area-canvas>
    <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
  </ui-color-picker-area>
  <ui-color-picker-slider channel="saturation" orientation="vertical">
    <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
  </ui-color-picker-slider>
</ui-color-picker>

The parts keep a hue while the color turns gray or black, so dragging back out of a corner returns to the same hue.

OKLCH

OKLCH spaces its colors evenly for the eye, so two colors with the same lightness look equally bright. Its edge with the colors a screen can show is a curve, which no gradient can draw. Add ui-color-picker-area-canvas to the area, and it paints the colors inside that edge and leaves the rest clear.

import "@ui-sdk/web/color-picker"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-color-picker aria-label="Accent" space="oklch" default-value="oklch(0.62 0.19 259)">
      <ui-color-picker-area>
        <ui-color-picker-area-canvas></ui-color-picker-area-canvas>
        <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
      </ui-color-picker-area>
      <ui-color-picker-slider channel="hue">
        <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
      </ui-color-picker-slider>
      <ui-color-picker-slider channel="alpha">
        <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
      </ui-color-picker-slider>
      <div data-slot="row">
        <ui-color-picker-swatch></ui-color-picker-swatch>
        <ui-color-picker-input>
          <input aria-label="OKLCH" />
        </ui-color-picker-input>
      </div>
    </ui-color-picker>
  `
}

export { mount }

Drag the thumb right, past the painted edge, and let go. The thumb moves back to the closest color inside.

While a drag holds a color past the edge, the value is already the closest color inside it, and every part has data-out-of-gamut. Once the drag ends, the thumb moves to that color. Colors stay inside sRGB by default. Set gamut="p3" for wide-gamut screens, or gamut="false" to allow any color:

<ui-color-picker
  aria-label="Accent"
  space="oklch"
  gamut="p3"
  default-value="oklch(0.7 0.25 150)"
>
  <!-- … -->
</ui-color-picker>

Presets and Channel Inputs

Put ui-color-picker-swatch-items inside ui-color-picker-swatches for preset colors. Each one is selected while the value is its color, however either is written, so #0000ff selects rgb(0 0 255). The list is one tab stop, and the arrow keys move between the presets.

ui-color-picker-channel-input edits one channel as a number and sets it on Enter, when you leave it, or with its arrows. ui-color-picker-eye-dropper picks from the screen in browsers that can. Elsewhere it's disabled, with data-unsupported, so you can hide it.

import "@ui-sdk/web/color-picker"
import { createElement, Pipette } from "lucide"

const presets = [
  "#ef4444",
  "#f97316",
  "#eab308",
  "#22c55e",
  "#0ea5e9",
  "#6366f1",
  "#a855f7",
  "#ec4899",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-color-picker aria-label="Label color" space="srgb" format="hex" default-value="#0ea5e9">
      <ui-color-picker-swatches aria-label="Presets">
        ${presets.map((preset) => `<ui-color-picker-swatch-item value="${preset}"></ui-color-picker-swatch-item>`).join("")}
      </ui-color-picker-swatches>
      <div data-slot="row">
        <ui-color-picker-channel-input channel="red"></ui-color-picker-channel-input>
        <ui-color-picker-channel-input channel="green"></ui-color-picker-channel-input>
        <ui-color-picker-channel-input channel="blue"></ui-color-picker-channel-input>
        <ui-color-picker-eye-dropper>
          <button aria-label="Pick from screen">${createElement(Pipette, { "aria-hidden": "true" }).outerHTML}</button>
        </ui-color-picker-eye-dropper>
      </div>
    </ui-color-picker>
  `
}

export { mount }

Choose a preset, or use the arrow keys between them. Type 255 into the first number to set red.

Put a ui-popover inside the picker to open it from a swatch. The parts inside the popup edit the same color, and the swatch in the trigger shows it.

import "@ui-sdk/web/color-picker"
import "@ui-sdk/web/popover"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-color-picker aria-label="Background" default-value="#22c55e">
      <ui-popover>
        <ui-popover-trigger>
          <button aria-label="Background">
            <ui-color-picker-swatch></ui-color-picker-swatch>
          </button>
        </ui-popover-trigger>
        <ui-popover-content>
          <ui-color-picker-area>
            <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
          </ui-color-picker-area>
          <ui-color-picker-slider channel="hue">
            <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
          </ui-color-picker-slider>
          <ui-color-picker-input>
            <input aria-label="Hex" />
          </ui-color-picker-input>
        </ui-popover-content>
      </ui-popover>
    </ui-color-picker>
  `
}

export { mount }

Press the Background swatch to open the picker, then drag to change the color.

Disabled

Set disabled. A disabled picker can't be focused or changed, and isn't submitted. A disabled <fieldset> around it disables it too.

import "@ui-sdk/web/color-picker"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-color-picker aria-label="Brand color" default-value="#0ea5e9" disabled>
      <ui-color-picker-area>
        <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
      </ui-color-picker-area>
      <ui-color-picker-slider channel="hue">
        <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
      </ui-color-picker-slider>
      <ui-color-picker-input>
        <input aria-label="Hex" />
      </ui-color-picker-input>
    </ui-color-picker>
  `
}

export { mount }

The thumbs can't be focused or dragged.

Set read-only to keep the parts focusable and the value submitted, while drags, keys and typing leave the color alone:

<ui-color-picker aria-label="Theme color" default-value="#0ea5e9" read-only>
  <ui-color-picker-swatch></ui-color-picker-swatch>
  <ui-color-picker-input>
    <input aria-label="Hex" />
  </ui-color-picker-input>
</ui-color-picker>

Controlled

Listen to valuechange for each change. Each change carries a reason, like drag, step-key or input-commit, and event.detail.color, the color the parts hold, which keeps a hue while the value turns gray. Call event.preventDefault() to keep the current value.

valuechange fires on every step of a drag. valuecommit fires once, when the drag, key press or typed color ends, so listen to it to save. The element's api property sets the color from anywhere with setValue(), like the Use Purple button below.

Console

import "@ui-sdk/web/color-picker"
import { log } from "./log"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div>
      <div data-slot="controls">
        <button type="button">Use Purple</button>
      </div>
      <ui-color-picker aria-label="Theme color" default-value="#0ea5e9">
        <ui-color-picker-area>
          <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
        </ui-color-picker-area>
        <ui-color-picker-slider channel="hue">
          <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
        </ui-color-picker-slider>
        <ui-color-picker-input>
          <input aria-label="Hex" />
        </ui-color-picker-input>
      </ui-color-picker>
    </div>
  `
  const picker = root.querySelector("ui-color-picker")!
  picker.addEventListener("valuecommit", (event) => {
    const { value, reason } = event.detail
    log(root, `committed: ${value} (${reason})`)
  })
  root
    .querySelector('[data-slot="controls"] button')!
    .addEventListener("click", () => picker.api.setValue("#663399"))
}

export { mount }

Drag across the area and let go, or press Use Purple. The console logs each committed color and its reason.

See State and Events for controlled state, cancellation and debugging.

Form

The picker submits the value under name, like #f97316, and a disabled picker submits nothing. A form reset returns it to default-value. Set form to join a form by its id.

Console

import "@ui-sdk/web/color-picker"
import "@ui-sdk/web/field"
import { log } from "./log"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <form data-slot="stack">
      <ui-field>
        <ui-field-label>Brand color</ui-field-label>
        <ui-color-picker name="brand" default-value="#f97316">
          <ui-color-picker-area>
            <ui-color-picker-area-thumb></ui-color-picker-area-thumb>
          </ui-color-picker-area>
          <div data-slot="row">
            <ui-color-picker-swatch></ui-color-picker-swatch>
            <ui-color-picker-slider channel="hue">
              <ui-color-picker-slider-thumb></ui-color-picker-slider-thumb>
            </ui-color-picker-slider>
          </div>
        </ui-color-picker>
      </ui-field>
      <div data-slot="row">
        <button type="submit" data-variant="solid">Save</button>
        <button type="reset">Reset</button>
      </div>
    </form>
  `
  const form = root.querySelector("form")!
  form.addEventListener("submit", (event) => {
    event.preventDefault()
    log(root, `Submitted brand=${new FormData(form).get("brand")}`)
  })
}

export { mount }

Change the color and press Save to log the submitted value. Reset restores the orange.

A color picker always has a value, so required only adds data-required.

Styling

Parts are unstyled, apart from the positions they need: thumbs get position: absolute and their place in percent, as inline styles. Give the area and sliders a size and their background variable, and center each thumb on its point with translate: -50% -50%.

Each part has a data-slot, such as color-picker-area, and its state attributes are listed under Data Attributes.

ui-color-picker

Variable	What it holds
`--color-picker-color`	The color as CSS, inside the gamut. On a swatch item, its own color. Use it to fill a thumb or a swatch.

ui-color-picker-area

Variable	What it holds
`--color-area-background`	Gradients that draw the area, when its channels are saturation and brightness or lightness. Unset for others, which a canvas paints.

ui-color-picker-area-thumb

Variable	What it holds
`--area-x`	Where the thumb is across the area, from 0 to 1.
`--area-y`	Where the thumb is up the area, from 0 at the bottom to 1 at the top.

ui-color-picker-slider

Variable	What it holds
`--color-slider-background`	A gradient through the slider's channel, with the other channels as they are.

ui-color-picker-slider-thumb

Variable	What it holds
`--color-slider-thumb-position`	Where the thumb is along the slider, as a percentage.

ui-color-picker-swatch

Variable	What it holds
`--color-picker-color`	The color as CSS, inside the gamut. On a swatch item, its own color. Use it to fill a thumb or a swatch.

ui-color-picker-swatch-item

Variable	What it holds
`--color-picker-color`	The color as CSS, inside the gamut. On a swatch item, its own color. Use it to fill a thumb or a swatch.

Data Attributes

ui-color-picker

[data-slot="color-picker"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-area

[data-slot="color-picker-area"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-area-thumb

[data-slot="color-picker-area-thumb"]

Attribute	What it means
`data-area-thumb`	Present on the area's thumb, which a press on the area moves and focuses.
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-slider

[data-slot="color-picker-slider"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-orientation`	`horizontalvertical`The slider's axis.
`data-channel`	`huesaturationbrightnesslightnesschromaredgreenbluealpha`The channel the part edits.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-slider-thumb

[data-slot="color-picker-slider-thumb"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-orientation`	`horizontalvertical`The slider's axis.
`data-channel`	`huesaturationbrightnesslightnesschromaredgreenbluealpha`The channel the part edits.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-input

[data-slot="color-picker-input"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-channel-input

[data-slot="color-picker-channel-input"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-channel`	`huesaturationbrightnesslightnesschromaredgreenbluealpha`The channel the part edits.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-swatch

[data-slot="color-picker-swatch"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-eye-dropper

[data-slot="color-picker-eye-dropper"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.
`data-unsupported`	Present when the browser can't pick a color from the screen.

ui-color-picker-swatches

[data-slot="color-picker-swatches"]

Attribute	What it means
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.
`data-required`	Present when the picker is required.
`data-out-of-gamut`	Present while a drag or a key holds a color outside the gamut. The value is the closest color inside, and the parts move there once the change commits.

ui-color-picker-swatch-item

[data-slot="color-picker-swatch-item"]

Attribute	What it means
`data-selected`	Present on the swatch item whose color is the value.
`data-disabled`	Present when the picker is disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when the picker shows its color but can't change it.

API Reference

Props are attributes in kebab case, like default-value and read-only. controller is a property. value is a live property and attribute. Callbacks are DOM events.

ui-color-picker

value?string: The value, as a CSS color, like "#0ea5e9" or "oklch(0.62 0.19 259)". Pass it to control the picker.
defaultValue?string: The value at first, when uncontrolled. A form reset returns to it.
valuechange event: Runs while the value changes: on every step of a drag or a key. details.color is the color, and details.cancel() stops it.
valuecommit event: Runs once an interaction that changed the value ends: the pointer lifts, a key is pressed, a swatch is picked. For saving.
space?ColorPickerSpace: The space the parts edit in, which decides their channels: "hsv" has hue, saturation and brightness, "hsl" hue, saturation and lightness, "srgb" red, green and blue, "oklch" lightness, chroma and hue.
format?ColorFormat: How the value is written: "hex", or a space in its CSS syntax, like "oklch".
gamut?false | ColorGamut: The colors the value can hold. A drag can go past the edge, and the value is the closest color inside it; once the drag ends, the picker moves there too. "p3" allows wide-gamut screens' colors, and false any color.
disabled?boolean: Disables every part: they can't be focused or changed, and the value isn't submitted.
readOnly?boolean: Keeps the parts focusable and the value submitted, but stops changes.
required?boolean: Marks it required, with data-required. A color picker always has a value, so it never blocks a form.
name?string: The name the value submits under. Without one, the picker submits nothing.
form?string: The id of a form to belong to, when it isn't inside that form.
controller?{ getValue: () => string; setValue: (value: string, options?: ColorPickerChangeOptions) => boolean; focus: () => void; }: Sets the value from anywhere. Create one with createColorPickerController().
debug?boolean: Logs every state change with its reason to the console, in development builds.

ui-color-picker-area

x?ColorChannel: The channel across, left to right.
y?ColorChannel: The channel up, bottom to top.

ui-color-picker-slider

channel?ColorChannel: The channel the slider edits, like "hue" or "alpha".
orientation?"horizontal" | "vertical": The slider's axis. Vertical sliders grow upward.

ui-color-picker-channel-input

channel?ColorChannel: The channel the input edits, like "hue" or "alpha".

ui-color-picker-swatch-item

valuestring: The color it picks, as any CSS color.

State

The same state shows as data attributes on each element.

valuestring: The value, as a CSS color.
colorColor: The color the parts show, in the picker's space. During a drag it can be outside the gamut.
spaceColorPickerSpace: The space the parts edit in.
disabledboolean: Whether it's disabled, by itself or by a <fieldset>.
readOnlyboolean: Whether it's read-only: the parts stay focusable, but nothing changes the value.
requiredboolean: Whether it's marked required.
outOfGamutboolean: Whether the color the parts show is outside the gamut, so the value is the closest one inside.

valuestring: The value, as a CSS color.
colorColor: The color the parts show, in the picker's space. During a drag it can be outside the gamut.
spaceColorPickerSpace: The space the parts edit in.
disabledboolean: Whether it's disabled, by itself or by a <fieldset>.
readOnlyboolean: Whether it's read-only: the parts stay focusable, but nothing changes the value.
requiredboolean: Whether it's marked required.
outOfGamutboolean: Whether the color the parts show is outside the gamut, so the value is the closest one inside.
channelColorChannel: The channel the slider edits.
channelValuenumber: The channel's value, in the units people read it in: degrees, percentages, 0 to 255 for red.
orientation"horizontal" | "vertical": The slider's axis.

selectedboolean: Whether the picker's color looks the same as this swatch's, whatever each is written in.
disabledboolean: Whether pressing it changes nothing, since the picker is disabled or read-only.

Reasons

event.detail.reason says why the value changed.

track-pressPointerEvent: A press on a slider's track or an area's surface moved the nearest thumb there.
dragPointerEvent: A slider thumb or a resize handle was dragged, or an item was dragged to a new place in a list.
step-keyKeyboardEvent: Arrow, Page Up, Page Down, Home or End stepped a slider or a number input.
input-commitKeyboardEvent | FocusEvent: Enter, or leaving a number input, committed what was typed: a number input parses, clamps and snaps it to the step, and an autocomplete closes its suggestions on it.
item-pressMouseEvent | KeyboardEvent: A member of a collection was chosen: a menu item, a tab, a radio or a checkbox item.
eye-dropper-pick
resetnone: A form reset.
restorenone: The browser restored state, like after going back, or a saved value was read back from storage.
imperativenone: A controller or api call, or a property set on a web component.

Controller

The element's api property has the same methods. The value property reads and sets the color.

setValue() takes any CSS color and an optional { reason, event }, fires the change event like a drag, and returns false when the color can't be read or the change is canceled.

getValue()() => string: The value, as a CSS color.
setValue(value, options?)(value: string, options?: ColorPickerChangeOptions | undefined) => boolean: Sets the value from any CSS color, as a user would. Returns false for text that isn't one.
focus()() => void: Moves focus to the area's thumb, or the first slider's.

Events

Events fire on their own element and don't bubble, with the new value in event.detail.value and the reason, event and color beside it. Calling preventDefault() on valuechange cancels the change.

Member	On	Description
`value` property, attribute	`ui-color-picker`	The value. The attribute sets where it starts, and is live
`api` property	`ui-color-picker`	The controller
`valuechange` event	`ui-color-picker`	`detail: { value, reason, event, color }`
`valuecommit` event	`ui-color-picker`	`detail: { value, reason, event, color }`, once the interaction ends

Accessibility

No WAI-ARIA pattern covers a color picker, so it's built from ones that do. The picker is a group. The area's thumb and each slider's thumb follow the WAI-ARIA slider pattern, and the area's thumb names both of its channels, like "Saturation 76%, Brightness 96%". The presets follow the listbox pattern, and each one is named by its color, like "vivid red", as is ui-color-picker-swatch.

The thumbs, inputs and presets are named in English by default. Pass aria-label to name them in another language.

Keyboard

Key	Does
Arrow keys	Move a thumb one step. On the area, Left and Right move across, Up and Down move up and down.
Shift with an arrow	Moves ten steps
Page Up or Page Down	Moves a tenth of the range, up the area or along a slider
Home or End	Moves to the start or end, across the area or along a slider
Enter	Reads the text in the input, or picks the focused preset
Escape	Puts the input's text back to the value

Each key press commits, like the end of a drag.

Tested Behavior

Every line below is an automated test.

Value

The parts show the default value.
A press on the area moves the color there, and commits when it lifts.
A drag along a slider follows the pointer and commits once.
The text input reads any CSS color on Enter, and text that isn't one goes back.
A channel input sets its channel in its own units.
A controller sets the value, and a canceled change keeps it.

Keyboard

Arrows step a slider, Shift ten steps, and each press commits.
Arrows move the area's thumb on both axes.
Swatches are one tab stop, arrows move between them, and a press picks one.

Forms

The value submits under its name, and a reset returns to the default.
A disabled picker can't be focused or changed, and submits nothing.

Gamut

In OKLCH, a color past the sRGB edge writes the closest one inside, and the thumb moves there once it lifts.
The canvas paints the area, with the colors outside the gamut left clear.

Runs in React, Vue and web components.