# ColorPicker

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

```ehtml 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

- [Slider](slider): Pick a value or a range by dragging thumbs along a track, with full keyboard support.
- [NumberInput](number-input): A number field with stepper buttons, keyboard steps, formatting, wheel and scrub.
- [PasswordInput](password-input): A password field with a button that shows and hides what was typed.
- [InputOTP](input-otp): A one-time code in separate slots, with paste, SMS autofill and a pattern.
- [TagsInput](tags-input): Type a list of tags into one field: add, edit, delete and paste them from the keyboard.
- [FileUpload](file-upload): Drop, paste or browse for files; see them listed with previews, sizes, errors and progress.