01
Overview
Full-featured input for selecting a color via hue, saturation, lightness, and alpha, emitting hex by default or another CSS Color 4 format via format.
Usage
02
When to use
Use when
- Letting users pick any color from the full spectrum with optional alpha.
- Composing a custom color with a fallback palette of preset swatches.
Avoid when
- Constraining selection to a fixed brand palette — use color-swatch-picker instead.
03
Examples
Color picker with alpha
Alpha slider enabled: emits an 8-character hex value. The footer row shows the full #rrggbbaa string.
Basic color picker
A color picker with preset swatches where the selected swatch shows a persistent check indicator without looking keyboard-focused.
Color picker without swatches
Omitting the swatches prop renders only the gradient, sliders, and footer row — useful when a freeform pick without preset guidance is needed.
Output format
The format prop controls the emitted string syntax (hex, rgb, hsl, hwb, or oklch) for the bindable value.
04
Props
Name | Type | Default | Description |
|---|---|---|---|
value bindable | text | '' | Bindable value. Reading the value yields a string in the configured
format (#rrggbb/#rrggbbaa for the 'hex' default, or modern
space-separated CSS Color 4 syntax with slash alpha for the others).
Setting the value accepts hex, rgb(), rgba(), hsl(), hsla(),
hwb(), or oklch() input, in either legacy comma syntax or modern
space-separated syntax — including whatever this component's own
format emits, so an emitted value always parses back; invalid input
is normalized to ''. Mounting does NOT normalize this prop itself —
a non-canonical value you pass in (short hex, legacy comma syntax, a
syntax mismatched with format) is left exactly as you passed it until
the first user-driven commit, which writes the fully normalized string
back. Only the rendered hidden form-mirror input is normalized at mount. |
alpha | boolean | false | Show the alpha slider. Default false. Per the CIN-104 ruling this is a
UI-affordance concern, not a value-mutation switch:
- A translucent value passed in programmatically (the initial value,
a later controlled update, or a native form reset) keeps its alpha
exactly as parsed, whether or not alpha is true — disabling the
slider alone never strips it.
- An *interactively* produced alpha (set by dragging the alpha slider
while it was visible) re-gates to fully opaque on the next
user-driven commit — any pointer drag, keyboard nudge, or swatch
selection — once alpha is false and the slider is gone. This is what
prevents a hidden, un-editable translucency from persisting forever
once the affordance to see or change it is removed.
This gate is uniform across every format — it is not a hex-only
concern. Independently of alpha, whether an alpha suffix appears at
all is decided by the configured format's own opacity-quantization
threshold, not literally "alpha equals 1": 'hex' treats alpha as
opaque once it rounds to the byte 0xff (any alpha >= ~0.998, e.g.
0.999), while every other format treats alpha as opaque once it
rounds to 1 at 4 decimal places (any alpha >= 0.99995, e.g.
0.99999). |
format | 'hex''rgb''hsl''hwb''oklch' | 'hex' | Output color format for the committed/emitted value. Default 'hex'.
Purely additive — existing consumers relying on the hex default are
unaffected. value stays a plain string regardless of format. |
name | text | Form field name. When set, a hidden input mirrors the current value for form submission. | |
swatches | string[] | Optional palette of preset colors rendered below the picker. | |
disabled | boolean | false | Disable interaction across the picker. |
label | text | 'Color picker' | Accessible label for the picker. Default 'Color picker'. |
onValueCommit | (color: string, reason: 'pointer' | 'swatch' | 'keyboard') => void | Fired on commit (pointer up, swatch click, slider key). | |
onValueChange | (color: string) => void | Fired on every intermediate update (drag, slider key, swatch click). |