useColorPicker

A headless sRGB color picker — a 2D saturation × brightness area, a hue channel, an optional alpha channel, a hex field, and optional preset swatches, assembled from ready-to-bind prop-getters. It owns the working color as an internal HSVA object (so the hue survives a grayscale round-trip when you drag into a corner and back). Underneath is a zero-dependency sRGB engine — a loose parser and a lowercase formatter, hex / rgb / hsv / hsl conversion, readable ink over a swatch by WCAG luminance — and the 2D-area math for pointer and keyboard. That engine is internal: it ships inside this composable, not as exports of its own.

This is the Vue binding; the framework-agnostic core lives in @oriui/headless, and the styled OriColorPicker is built on it. Like useToolbar, this is a compositional helper — deterministic sRGB + 2D-area math exposed as prop-getters and setters — not the OriHeadless adapter contract: a color picker has no swappable engine and no async state to project, so (unlike useDialog's machine-behind-a-swappable-adapter shape) there is nothing to swap. It does reuse the same core roving helpers as the toolbar (rovingIntent / resolveRovingIndex) for the preset listbox — see the roving taxonomy framing.

Import

import { useColorPicker } from '@oriui/headless/vue'

Options

useColorPicker(options) takes its options as a getter — useColorPicker(() => ({ … })), like useToolbar / useMenu — so value / format / disabled stay reactive. The color crosses the boundary as a lowercase string (bind to v-model), with the dual-event convention: onInput streams live on every interaction tick, onChange commits once on release / keyboard settle (one undo entry).

Returns

Reactive state, prop-getters (spread with v-bind), and imperative setters. HSVA is { h, s, v, a } (h ∈ [0, 360), s / v / a ∈ 0, 1); RGB is { r, g, b } (0–255).

Reactive state

Prop-getters

Setters & actions

Usage

The picker is assembled from the parts you spread its getters onto — exactly what the styled OriColorPicker wraps. Bind areaProps on the 2D surface with its two visually-hidden range inputs, drive a slider off hue / setHue, feed the hex field through setHex, and render presets as the roving listbox.

<script setup lang="ts">
import { ref, watch } from 'vue'
import { useColorPicker } from '@oriui/headless/vue'
import type { ColorFormat } from '@oriui/headless/vue'

const { format = 'hex', label, presets } = defineProps<{ format?: ColorFormat; label?: string; presets?: string[] }>()

const model = defineModel<string>()
const emit = defineEmits<{ change: [value: string] }>()

// Options are a GETTER, so value / format stay reactive. onInput drives v-model (live),
// onChange commits (one undo entry).
const cp = useColorPicker(() => ({
    value: model.value,
    format,
    presets,
    onInput: (next) => {
        model.value = next
    },
    onChange: (next) => emit('change', next)
}))

// The hex field holds a local draft so a partial entry isn't reformatted mid-type; cp.hex re-seeds it.
const hexDraft = ref(cp.hex.value)
watch(
    () => cp.hex.value,
    (hex) => {
        hexDraft.value = hex
    }
)
</script>

<template>
    <div role="group" :aria-label="label">
        <!-- 2D saturation × value area. The two visually-hidden range inputs are the a11y surface
             (role=slider, focusable, form value); the area's keydown routes the arrows across both axes. -->
        <div v-bind="cp.areaProps.value">
            <span :style="cp.areaThumbStyle.value" aria-hidden="true"></span>
            <input class="sr-only" v-bind="cp.getChannelInputProps('saturation')" />
            <input class="sr-only" v-bind="cp.getChannelInputProps('value')" />
        </div>

        <!-- Preview swatch — role=img named by the current color, ink chosen for contrast. -->
        <span
            role="img"
            :aria-label="cp.hex.value"
            :style="{ background: cp.swatchColor.value, color: cp.ink.value }"
        />

        <!-- Hue slider — a native range in [0, 360); commit on release. -->
        <input
            type="range"
            :min="0"
            :max="360"
            :step="1"
            :value="cp.hue.value"
            :aria-label="cp.labels.value.hue"
            @input="cp.setHue(Number(($event.target as HTMLInputElement).value))"
            @change="cp.commit"
        />

        <!-- Hex field — setHex parses and commits, returning false on a bad hex. -->
        <input
            :value="hexDraft"
            :aria-label="cp.labels.value.hex"
            spellcheck="false"
            @input="hexDraft = ($event.target as HTMLInputElement).value"
            @blur="cp.setHex(hexDraft)"
            @keydown.enter="cp.setHex(hexDraft)"
        />

        <!-- Presets — a single-select roving listbox (one tab stop; arrows move focus). -->
        <div v-if="presets?.length" v-bind="cp.presetGroupProps.value" @keydown="cp.onPresetKeydown">
            <button v-for="(preset, i) in presets" :key="preset" v-bind="cp.getPresetProps(preset, i)"></button>
        </div>
    </div>
</template>

Accessibility

The prop-getters carry the ARIA and keyboard contract; nothing is hand-rolled that a native control already provides.

• The 2D area is two visually-hidden native <input type="range"> — one per axis (getChannelInputProps('saturation') / ('value')). Each is a real role="slider" with its own aria-label and aria-valuetext ("60%"), focusable, announced, and form-associable. The arrow keys are routed across both axes by areaProps' onKeydown (a single native range spans only one axis); it preventDefaults the navigation keys and bubbles from the focused channel input. getChannelInputProps' own onInput still covers an assistive technology that sets a channel value directly.
• The preview swatch is role="img", named by the current color; ink picks black or white content for WCAG contrast over it.
• Presets are a single-select role="listbox" (presetGroupProps) with roving tabindex — one tab stop, arrow keys move real DOM focus (onPresetKeydown, wrapping), aria-selected marks the active color. Each chip is a role="option" button labeled by its color.
• Name the whole control yourself, with an aria-label on the root role="group" (as the example does); disabled blocks the area drag / keyboard and disables the channel inputs.

Area keyboard (focus is on a channel input; the area routes the key):

See also

• @oriui/headless — the framework-agnostic core, and the roving helpers this binding reuses.
• Color picker — the styled OriColorPicker built on this composable.
• Slider — the native-range primitive the styled picker reuses for the hue / alpha channels.
• Popover — compose the inline picker into a popover for a swatch-triggered flow.