ColorPicker

Click the trigger swatch to open a color panel with a 2D saturation-brightness field + vertical hue rail, preset colors, RGB and hex input, an alpha channel, a gradient mode (multi-stop editing), tolerant value parsing, clearing and a controlled open state; it can also render inline without a popup. The popup panel is positioned with a fixed viewport anchor and auto-flips / clamps at viewport edges.

Basic Usage

Basic

Example

Click the trigger to toggle the panel; pick saturation and brightness on the 2D color field, pick hue on the vertical hue rail, or edit the RGB numbers / pick a preset color for an instant update. With the trigger focused, press Esc or click outside to close.

Custom Preset Colors

Custom preset (any CSS color + labeled items + rows/columns)

Example

preset takes a JSON array: items may be any CSS color string (color names, rgb(), hsl(), hex — parsed tolerantly), or { color, label } objects where label becomes the swatch's accessible name for screen readers. preset-columns / preset-rows set the number of columns and visible rows (extra items are truncated).

Disabled and Readonly

disabled / readonly

Example

disabled fully disables the picker (grayed-out trigger, not clickable); readonly shows the current color without allowing changes — the trigger cannot open the panel and no open events are emitted.

Sizes

size levels

Example

size="large" / default / size="small" reuse the --oas-control-height-* control height tokens.

Alpha Channel

Alpha (show-alpha / disabled-alpha)

Example

show-alpha reveals the alpha slider and a checkerboard backdrop — translucent swatches show the checker pattern and values serialize as 8-digit hex (#rrggbbaa), or rgba() when combined with color-format="rgb". disabled-alpha keeps the channel visible but disables the slider (existing transparency is preserved).

Format and Tolerant Parsing

Tolerant parsing + color-format + uppercase

Example

value parses CSS color names, rgb()/hsl() and 3/4/6/8-digit hex and normalizes them for display. color-format="rgb" switches display and commit to rgb()/rgba(); uppercase serializes hex in capitals.

Empty Value and Clearing

clearable + value-on-clear

Example

With clearable, an open panel shows a clear button: clearing empties value and renders the "not selected" placeholder, emitting oas-clear (detail carries the previous value) and oas-change (empty detail). value-on-clear sets the value to fall back to after clearing (e.g. #000000).

Custom Trigger

Custom trigger slot + show-text

Theme color

Example

slot="trigger" fully customizes the trigger content (the value text can still be shown next to it); show-text="false" hides the value text (default is true).

Controlled Open

Controlled open + oas-open-change

Example

The open attribute is the single source of truth (controlled both ways): external setAttribute/removeAttribute('open') and internal clicks / outside clicks / Esc converge on it, and every change emits oas-open-change (detail { open }). Setting open initially does not emit.

Eyedropper

Eyedropper (EyeDropper)

Chromium only: open the panel and click the eyedropper icon, then pick a color anywhere on screen. On unsupported browsers the button is hidden.

Example

Edge Avoidance (right-edge trigger reproduction)

Right-edge trigger no longer overflows or clips (fix verification)

Appearance-tab style right-aligned scenario: a narrow right-aligned container with `overflow: hidden`. The panel uses fixed viewport anchoring (12-way `placement`, default `bottom`), so it always stays inside the viewport instead of widening the page or being clipped by ancestors — it clamps or flips when space runs out.

Example

2D Color Field

Designer capability ships with the main entry: the main entry @oas-ui/ui/form/color-picker already bundles the 2D color field / vertical hue rail / gradient editor (mode="gradient", including the gradient demos below and the inline gradient form; import registers it) — no explicit import needed. Consumers that only need the default behavior (swatch presets + hex/RGB input + alpha) can slim down with the pure-core entry @oas-ui/ui/form/color-picker/core — it omits the capability, so mode="gradient" silently degrades with a dev hint; explicitly import '@oas-ui/ui/form/color-picker/designer' (import registers it) or switch back to the main entry. The full @oas-ui/ui entry and the CDN form-family bundles include it too.

The three H/S/V tracks were refactored into a more standard two-dimensional picker: an SV field (saturation horizontally, brightness vertically) plus a vertical hue rail. Both support pointer dragging and arrow-key stepping, with role="slider" + aria-valuetext semantics exposing both dimensions.

2D color field + hue rail

Example

Gradient Mode

Set mode="gradient" to enter gradient editing: every stop on the gradient axis is colored independently — add / remove / drag / nudge stops, and value serializes to a linear-gradient(...) string.

Gradient (mode=gradient)

Example

Gradient + alpha (show-alpha)

Example

Inline Standalone Panel

inline renders the panel in place (no trigger / popup), so hosts composing their own overlay reuse the same color controls directly.

inline (panel only)

Example

Events

Change events

Example

Recent Colors (recent / recent-key)

recent: committed colors gather at the panel bottom for re-selection

Example

recent + recent-key: localStorage persistence (survives reload)

Example

recent enables the recent-colors strip: each committed color is pushed onto a stack (deduped, capped at 8, newest first) and shown as clickable swatches at the bottom of the panel. recent-key names the localStorage key used to persist the list across sessions; without it the list only lives in memory for the current instance.

API

oas-color-picker

Attributes

Attribute	Description	Type	Default
clearable	Show a "clear" button in the panel footer (visible when open and a value is set): writes back value-on-clear or empties value, then emits oas-clear + oas-change	boolean	—
color-format	Output format: hex (default) / rgb; determines the value written back and the trigger text format	string	hex
disabled	Disabled	boolean	—
disabled-alpha	Disable the alpha slider (effective when show-alpha is on)	boolean	—
inline	Inline mode: the panel renders in place always visible with the trigger hidden, no popup positioning contract, no oas-open-change	boolean	—
mode	Picking mode: single (default) / gradient (gradient editor; requires the designer capability — silently inert with a one-time dev warning when missing)	string	single
open	Controlled panel visibility (boolean attribute); ineffective while readonly/disabled; emits oas-open-change on change	boolean	—
placement	Panel placement, 12 directions: top/bottom/left/right with -start/-end (default bottom); auto right-aligns when the trigger nears the viewport right edge, flips upward when space below is insufficient, and clamps back inside the viewport	string	bottom
preset	Preset color array (JSON)	string	—
preset-columns	Preset swatch column count (positive integer, default 8)	string	—
preset-rows	Preset swatch row cap (positive integer; unset shows all presets)	string	—
readonly	Read-only: the trigger cannot open the panel and all edits are blocked	boolean	—
recent	Recent-colors strip: each committed color is pushed onto a deduped, 8-capped, newest-first stack shown as clickable swatches	boolean	—
recent-key	localStorage key used to persist recent colors (with recent; memory-only when omitted)	string	—
show-alpha	Enable the alpha channel: alpha slider in the panel, checkerboard under translucent trigger/preset swatches, alpha included in the value output	boolean	—
show-text	Show the color text on the trigger (default true; "false" shows the swatch only)	string	true
size	Trigger size: small / medium (default) / large	—	—
uppercase	Uppercase the output color value (hex letters A–F)	boolean	—
value	Current color (hex)	string	—
value-on-clear	Fallback value on clear: clicking clear writes this back instead of emptying value	string	—

Property (JS property; see each row for attribute reflection)

Property	Description	Type	Default
value	Current value: the color string (read from the controlled value attribute)	string	—

Events

Event	Description
oas-change	Color change, detail: { value }
oas-clear	Emitted after "clear" is clicked; detail: { value } holds the previous value; oas-change follows (detail.value is the new value / empty string)
oas-open-change	Emitted when panel visibility changes, detail: { open } (not emitted in inline mode)

Slots

Name	Description
trigger	Custom trigger (replaces the default swatch button)

CSS Variables

CSS Variable	Default
--oas-glass-blur	none
--oas-glass-ring	transparent

Keyboard: with the trigger button focused, Enter/Space toggles the panel and Esc closes it; Esc also closes from a focused panel input, and clicking outside closes.