Headless / Specialized

ColorPicker

ColorPicker is a headless HSV colour picker. Drag the saturation-value plane for chroma and brightness, the hue slider for hue, the alpha slider for transparency — and toggle between hex, rgb, and hsl output.

Loading playground…

What it is

A single component built around an internal HSV model. It renders a saturation-value drag plane, a hue slider, an optional alpha slider, and a format toggle — each driven by pointer and keyboard. The HSV state is kept internally so hue survives a trip through low-saturation or zero-value regions where the round-trip through RGB would lose it.

The value is a CSS colour string in the current format. ColorPicker also exports parseColor and formatColor — the parse-and-print pair it uses internally — for converting colour strings yourself.

Install

example.tsx

yarn add @usemotif/headless

example.tsx

import { ColorPicker } from '@usemotif/headless';

API

ColorPicker

stable

function ColorPicker(props: ColorPickerProps): JSX.Element

value / defaultValue / onValueChangestring / string / (next: string) => void

The colour as a CSS string, controlled or uncontrolled. The string follows `format`.

format / onFormatChangeColorFormat / (next: ColorFormat) => void

The output format — `hex`, `rgb`, or `hsl`. Controllable.

allowAlphaboolean= false

Render the alpha slider. Applies only when `format` is not `hex`.

formatsreadonly ColorFormat[]= ['hex', 'rgb', 'hsl']

Which formats the toggle offers. Pass `[]` to hide the toggle.

disabledboolean= false

Disables all the drag surfaces and the toggle.

style / saturationValueStyle / hueSliderStyle / …CSSProperties

Inline styles for the root, the SV plane, the SV thumb, the hue slider, and the alpha slider.

parseColor / formatColor

example.tsx

function parseColor(input: string): HSVColor;
function formatColor(color: HSVColor, format: ColorFormat): string;

parseColor accepts #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), rgba(), hsl(), and hsla(), falling back to opaque black on unparseable input rather than throwing. formatColor prints an HSV colour back out in the requested format.

Accessibility

The saturation-value plane is a role="application" — it captures the arrow keys for two-dimensional movement, which a plain slider role cannot express; Shift takes larger steps. The hue and alpha sliders are each role="slider" with the standard keyboard model. The format toggle is a role="radiogroup". Every surface is reachable and operable without a pointer.

Colour is hard to convey to a non-sighted user. Pair ColorPicker with a visible, editable text field showing the current value — the format toggle's output is exactly that string — so the colour can be read and entered, not only dragged.

Examples

A hex picker:

example.tsx

<ColorPicker value={brandColor} onValueChange={setBrandColor} />

An rgba picker with alpha:

example.tsx

<ColorPicker
value={overlayColor}
onValueChange={setOverlayColor}
format="rgb"
allowAlpha
/>

Converting a colour string by hand:

example.tsx

import { parseColor, formatColor } from '@usemotif/headless';
 
const hsv = parseColor('#3b82f6');
const asHsl = formatColor(hsv, 'hsl');