◇

ColorArea

2 parts

The 2D saturation/value square of a colour picker. The x-axis maps saturation (0 at the left → 1 at the right) and the y-axis maps brightness/value (1 at the top → 0 at the bottom). It works standalone — owning its own HSVA via v-model / defaultValue — or, nested inside a ColorFieldRoot, reads and writes that shared colour so the whole picker cluster stays in sync. A pointer press anywhere in the area sets saturation and brightness at once; the --color-area-hue CSS variable is exposed so the consumer can paint the full-saturation / full-value hue background. Provides context to ColorAreaThumb. Reach for it as the main square of a colour picker.

Source

Demo

Loading demo…

Anatomy

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

vue

import {
  ColorAreaRoot,
  ColorAreaThumb,
} from '@robonen/primitives/color/color-area';

<ColorAreaRoot>
  <ColorAreaThumb />
</ColorAreaRoot>

API Reference

ColorAreaRoot

Root

The 2D saturation/value square of a colour picker. The x-axis maps saturation (`0` at the left → `1` at the right) and the y-axis maps brightness/value (`1` at the top → `0` at the bottom). It works standalone — owning its own `HSVA` via `v-model` / `defaultValue` — or, nested inside a `ColorFieldRoot`, reads and writes that shared colour so the whole picker cluster stays in sync. A pointer press anywhere in the area sets saturation and brightness at once; the `--color-area-hue` CSS variable is exposed so the consumer can paint the full-saturation / full-value hue background. Provides context to `ColorAreaThumb`. Reach for it as the main square of a colour picker.

Prop	Type	Default	Description
`defaultValue`?	`HSVA`	`{ h: 0, s: 1, v: 1, a: 1 }`	Uncontrolled initial colour.
`step`?	`number`	`0.01`	Keyboard step for saturation/value nudges (`0–1`).
`largeStep`?	`number`	`0.1`	Large keyboard step (Shift+Arrow / Page keys, `0–1`).
`dir`?	`ColorAreaDirection`	—	Writing direction (inherited from `ConfigProvider` when omitted).
`disabled`?	`boolean`	`false`	Disable interaction.
`modelValue`?	`HSVA \| null`	—	Two-way bound value (`v-model`).

Emits

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

ColorAreaThumb

Thumb

The 2D handle of a `ColorAreaRoot`. A single thumb carries two axes (saturation on x, brightness on y) which one `aria-valuenow` cannot express, so it is exposed as `role="slider"` with `aria-valuenow` set to the primary axis (brightness) and `aria-valuetext` conveying **both** channels (e.g. `"Saturation 60%, Brightness 80%"`). Keyboard: Left/Right nudge saturation by `step` (direction-aware), Up/Down nudge brightness (Up = brighter), Shift+Arrow uses the large step, Home/End set saturation to `0`/`1`, and Page Up/Down change brightness by the large step. It positions itself at `left = saturation`, `top = 1 − brightness`. Pass `valueText` to override the announced text and `aria-label` for the accessible name (default `"Saturation and brightness"`).

Prop	Type	Default	Description
`valueText`?	`(saturation: number, value: number) => string`	—	Override the `aria-valuetext` describing both axes. Receives saturation and value/brightness as `0–1` floats.