◇

ColorField

5 parts

The composite root of the colour-picker cluster. It owns the canonical HSVA colour (controlled via v-model, uncontrolled via defaultValue) and provides a shared context that ColorArea, HueSlider, and AlphaSlider read and write into, keeping every control in sync without round-tripping through RGB. The model accepts either an HSVA object or any CSS colour string (#rrggbb, rgb()/rgba(), hsl()/hsla()) via parseColor and emits in the configured format. Compose it with ColorFieldSwatch, ColorFieldInput, ColorFieldLabel, and ColorFieldHiddenInput. Reach for it whenever you need a full, accessible colour picker tied to a form value.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  ColorFieldRoot,
  ColorFieldHiddenInput,
  ColorFieldInput,
  ColorFieldLabel,
  ColorFieldSwatch,
} from '@robonen/primitives/color/color-field';

<ColorFieldRoot>
  <ColorFieldHiddenInput />
  <ColorFieldInput />
  <ColorFieldLabel />
  <ColorFieldSwatch />
</ColorFieldRoot>

API Reference

ColorFieldRoot

Root

The composite root of the colour-picker cluster. It owns the canonical {@link HSVA} colour (controlled via `v-model`, uncontrolled via `defaultValue`) and provides a shared context that `ColorArea`, `HueSlider`, and `AlphaSlider` read and write into, keeping every control in sync without round-tripping through RGB. The model accepts either an `HSVA` object or any CSS colour string (`#rrggbb`, `rgb()/rgba()`, `hsl()/hsla()`) via `parseColor` and emits in the configured `format`. Compose it with `ColorFieldSwatch`, `ColorFieldInput`, `ColorFieldLabel`, and `ColorFieldHiddenInput`. Reach for it whenever you need a full, accessible colour picker tied to a form value.

Prop	Type	Default	Description
`defaultValue`?	`HSVA \| string`	`'#ff0000'`	Uncontrolled initial value (`HSVA` object or CSS colour string).
`format`?	`ColorFormat`	`'hex'`	Serialization format used for `update:modelValue`, the swatch label, the input string, and the hidden form input.
`disabled`?	`boolean`	`false`	Disable all interaction across the cluster.
`name`?	`string`	—	Hidden form input `name` (enables native form submission).
`modelValue`?	`HSVA \| string \| null`	—	Two-way bound value (`v-model`).

Emits

Event	Payload
`update:modelValue`	`[value: HSVA \| string \| null]`

ColorFieldHiddenInput

HiddenInput

A visually-hidden native `<input>` carrying the surrounding `ColorFieldRoot`'s formatted colour under `name`, so the colour participates in native form submission and constraint validation. Renders nothing unless `name` is set. Place it inside a `ColorFieldRoot`.

Prop	Type	Default	Description
`name`?	`string`	—	Form field `name`. The input is only rendered when this is set.
`required`?	`boolean`	—	Mark the hidden input as required for native validation.

ColorFieldInput

Input

A native text `<input>` bound to the formatted colour string of the surrounding `ColorFieldRoot`. As the user types it parses the value via `parseColor`; a valid colour updates the canonical state, an invalid one is left uncommitted and `aria-invalid` flips to `true` so the field reflects the live parse state. While the input is focused it shows the user's in-progress text; on blur it re-syncs to the canonical formatted value. Place it inside a `ColorFieldRoot`.

No props or events — renders its element and forwards attributes.

ColorFieldLabel

Label

The accessible name for the whole colour-picker cluster. It renders a `<label>` (or any element via `as`) with a generated `id` that it registers into the `ColorFieldRoot` context, so the otherwise-orphaned sub-pickers (`ColorArea`, `HueSlider`, `AlphaSlider`) and `ColorFieldInput` can reference it via `aria-labelledby`. This closes the "four orphaned controls" a11y gap. Place it inside a `ColorFieldRoot`.

Prop	Type	Default	Description
`id`?	`string`	—	Override the generated label id.

ColorFieldSwatch

Swatch

A presentational swatch showing the current colour of the surrounding `ColorFieldRoot`. It paints its `background` from the canonical colour and, unless `decorative`, exposes itself as `role="img"` with an `aria-label` carrying the formatted colour string so the swatch is announced to assistive technology. Place it inside a `ColorFieldRoot`.

Prop	Type	Default	Description
`decorative`?	`boolean`	`false`	When `true`, the swatch is hidden from assistive technology (`aria-hidden`) instead of being announced as an image.
`label`?	`string`	—	Override the accessible label (defaults to the formatted colour).