Color picker

Default density Compact density Restart from the initial state Show the copyable source

Usage

The value is a CSS Color 4 string serialized in the active format, while the widget keeps a floating-point color internally, so switching formats or dragging never accumulates rounding. Give the picker an inline size; its surfaces fill the width they get.

The default composition is the saturation/brightness area with hue and alpha Sliders, a format Select and numeric fields.

Popup

picker="popup" puts the panel in a Popover opened from a Color input swatch. The popup header compares the original and current colors, copies the value and offers the eyedropper; pressing the original restores it.

Default density Compact density Restart from the initial state Show the copyable source

formatSelect, preview and eyedropper hide their header items as they hide the inline ones. Author slot="trigger" content to replace the default trigger. open / defaultOpen, setOpen(open, reason?) and close() forward to the Popover, which remains the state owner; its tp-open-change and tp-open-change-complete events are re-dispatched from the widget with the Popover’s reasons. Opening moves focus to the first dimension of the active view and closing returns it to the trigger.

A Color input in the trigger slot opens the popup instead of the browser’s picker and always shows the picker’s color. An inline one shows the color as a row with its text: a color typed there becomes the picker’s value.

Default density Compact density Restart from the initial state Show the copyable source

In a form

With a name, the picker submits its string through the surrounding form and takes part in reset. Recent colors are application state: record each commit and hand the last few back through recent, and they appear in the popup’s swatch strip.

Default density Compact density Restart from the initial state Show the copyable source

Save Reset

Pick a color, then save.

The widget is form-associated: name submits the value string, uncontrolled reset restores the default (form-reset), required reports a missing value with strings.valueMissing, and restoration updates uncontrolled state. Place the picker inside tp-field for a label, description and error; the Field names the root group and label activation focuses the first dimension.

Formats

format never follows the notation you supply: any CSS color goes in, and value reads back in the active format. formats limits the format Select; alpha="false" drops alpha and keeps every published value opaque.

Default density Compact density Restart from the initial state Show the copyable source

The widget accepts every CSS Color 4 absolute notation (hex with 3, 4, 6 or 8 digits, legacy and modern rgb() / hsl(), hwb(), lab(), lch(), oklab(), oklch(), color() in the sRGB, linear sRGB and XYZ spaces, named colors, transparent, none) plus the non-CSS hsv() and device-cmyk() notations. Whatever notation an owner supplies, value reads back as the canonical serialization of the active format: modern space-separated syntax, lowercase, alpha appended as / a only when it is below 1 after rounding to two decimals.

Changing the format proposes tp-format-change (cancelable); once accepted, the widget publishes the re-serialized value through a non-cancelable tp-value-change followed by tp-value-commit with metadata.formatChange: true. The color itself is invariant across formats.

The read-only color property exposes the floating-point { space, coords, alpha } record; hsv() and device-cmyk() strings are not parsable by the browser, so consumers that need CSS read color or pick another format.

Typing a hex value without alpha digits keeps the current alpha, text that does not parse reverts to the current color, and a hue of 360 stays 360. A drag through black, white or gray keeps the last chromatic hue and saturation.

Views

views lists the available views; more than one renders a tab strip. Channel sliders edit each channel of the format, the wheel derives harmony colors from a base, and the triangle is the classic hue ring around an HSV triangle.

Default density Compact density Restart from the initial state Show the copyable source

Default density Compact density Restart from the initial state Show the copyable source

default-harmony sets the starting rule; a harmony attribute makes the rule controlled. The ring around the wheel copies each harmony color on press.

Derived handles follow the base; under custom every handle is its own hue and saturation pair, seeded from the previous rule so the layout does not jump.

harmonyColors lists the base color first and then the derived ones, in the active format, so the palette can drive the rest of your interface.

Default density Compact density Restart from the initial state Show the copyable source

Swatches and schemes

Saved swatches are a property, set from data; recent colors are application-owned too, since the widget keeps no history. The schemes view generates tints, shades and related strips from the current color.

Default density Compact density Restart from the initial state Show the copyable source

swatches accepts strings or { label, colors } groups.

Without consumer data the widget generates tints, shades, tones, analogous, complementary, triad and tetrad rows in OKLab/OKLCH from the current color, every entry gamut-mapped to sRGB; the rows stay pinned to the color they were generated from until the “Generate schemes” wand is pressed, so strips never move under a press. Supply schemes ({ label, palettes: [{ label, colors }] }[]) to replace generation with templates chosen through the Template Select. Pressing a scheme or saved swatch proposes that color (item-press, or keyboard when selected from the keyboard); pressing the selected swatch again proposes nothing.

Listening to changes

Drags publish tp-value-change while moving and one tp-value-commit on release, so expensive work belongs on the commit. Cancel a tp-value-change to reject a proposal.

Default density Compact density Restart from the initial state Show the copyable source

Saved: #facc15

metadata carries the floating-point color of the proposal and, when known, the edited channel, the surface (area, wheel, triangle, slider, field, swatch, scheme, eyedropper, compare) and formatChange. Only the widget’s own events cross its boundary; the Sliders, Inputs, Selects, Tabs, Toggle Groups and Popover inside never leak their lane events.

Escape during a drag restores the pre-press value (escape-key) and pointer cancellation restores it as well (pointer); neither commits. A capture lost before the release, or a move that reports no pressed button, ends the drag where the pointer last was and commits it (drag), so the last release always settles. Keyboard steps, wheel scrubbing (opt-in through allowWheelScrub), swatches, the eyedropper, hex Enter and blur, and setValue() commit immediately (a paste counts as typing, so it commits on Enter or blur). Numeric fields commit when the Number field commits (Enter or blur).

Controlled, with limits

Set value to own the color: each proposal arrives in onValueChange, and only the values you write back are shown. event.detail.metadata.color carries the proposal as floating-point coordinates, so you can check it before accepting. This one refuses colors too light for white button text; drag toward white and the handle stops.

Default density Compact density Restart from the initial state Show the copyable source

Start free trial

A refused proposal leaves the value, every surface, the fields and the form state unchanged.

Supply value for a controlled picker or defaultValue for an uncontrolled one; the mode stays fixed for the element’s lifetime. The same rule applies to the format, view, harmony and open lanes.

Trimming the panel

The controls around the color surface can each be turned off. fields="false" removes the row of value boxes, format-select="false" the format Select, preview="false" the color swatch and eyedropper="false" the screen picker, leaving a surface for quick, approximate choices.

Default density Compact density Restart from the initial state Show the copyable source

The fields row (fields), format Select (formatSelect), preview swatch (preview) and eyedropper (eyedropper, rendered only where the platform EyeDropper API exists) are independent toggles.

Sizes and states

Default density Compact density Restart from the initial state Show the copyable source

readonly keeps focus and form submission but blocks every edit; disabled removes both.

size (sm, default, lg) scales the area, tracks, thumbs and swatches; shape (square, round) shapes the preview and swatches.

Right-to-left

Under dir="rtl" the area and the Sliders mirror with the writing direction, so dragging toward the end edge still raises the value. Angular surfaces, the wheel and the hue ring, keep their geometry.

Default density Compact density Restart from the initial state Show the copyable source

Keyboard and pointer

Every editable dimension is a hidden native range input inside its thumb or handle.

Surface / controlKeysArea, triangleLeft/Right saturation, Up/Down brightness on either input; Page Up/Down, Home, End act on the focused dimensionHue ring, wheel hueLeft/Right/Up/Down step the hue; it wraps past 0 and 360Wheel saturationarrows step saturation; Home/End reach the boundsHue and alpha Slidersthe Slider keyboard model; the hue Slider wraps past 0 and 360 instead of clampingChannel Sliders / fieldsSlider and Number field models (arrows, Page keys, Home/End, Shift/Control/Meta for the large step, Alt for the small one)Swatches, schemesToggle Group roving focus; Space/Enter selectPopupEnter/Space on the trigger opens; Escape closes and returns focus; the header’s Select, original swatch, Copy button and eyedropper are ordinary stops ahead of the surface

On the surfaces and Sliders arrow steps use the channel step; Shift, Control or Command and the Page keys use the large step, Alt the small step. The numeric fields follow the Number field model with their last displayed digit as the step (0.001 for the OK channels, 0.1 for Lab and the OKLCH hue, 1 elsewhere), so every value the fields show is valid; Shift still uses the channel’s large step. Horizontal arrows follow the writing direction on the area and Sliders; angular axes (wheel, ring) do not flip. Pointer presses capture the pointer, coalesce movement to one proposal per frame and release once. A press inside a handle (the area thumb, a wheel handle, the ring or triangle thumb, a Slider thumb) keeps the pointer’s offset from the handle’s center, so the handle moves with the pointer instead of jumping under it; a press elsewhere moves the handle to the press point. Under a harmony rule the derived wheel handles follow the base, so a press on one of them moves nothing, and where a derived handle shares or overlaps the base’s position the base still takes the press. Shift snaps coarsely and Alt moves finely on Sliders.

Constituents and accessibility

Every dimension exposes the slider role with an accessible name of the form ${label}: ${name} (Hue, Saturation, Brightness, Lightness, Red, …, Alpha) and value text in display precision with its unit (242°, 66%, 0.628). The area and triangle inputs sit in a group named “Saturation and brightness”, the wheel in “Hue and saturation”; custom harmony handles expose “Harmony color N: Hue/Saturation”. The root is a group named by label (or aria-label). Tab order per view: tabs, surface inputs, eyedropper, hue, alpha, format Select, fields, alpha field, then one roving stop per swatch group; in the popup the header (format Select, original swatch, Copy button, eyedropper) precedes the surface. The original swatch is a Button named “Restore the original color” plus the original serialization; the current swatch is decorative; the Copy button announces its result. Harmony palette segments are Copy buttons named “Copy color” plus their serialization, grouped as “Harmony palette”, in the tab order right after the wheel. strings overrides every name (hue, alpha, eyedropper, compare, original, copy, palette, savedColors, viewWheel, formatOklch, harmonyTriad, schemeTints, …) for localization; locale formats the numeric fields.

API Reference

Every element also accepts motion-policy.

Related

Components, widgets and patterns that use this one.