Hooks

Three hooks power the components. useColorState is the one you reach for most — it holds the color and hands you every setter the primitives need.

useColorState

The core state hook. Give it an initial color; it returns the current color in every format plus the setters that ColorArea, the sliders, and the inputs expect.

const {
  hsva,
  colorValue,
  updateColor,
  setFromString,
  startDrag,
  endDrag,
} = useColorState('#6366F1');

// colorValue.hex, colorValue.oklch, … are all live

#6366f1

Returns

Key	Type	Description
`hsva`	`HSVA`	Internal HSVA representation.
`colorValue`	`ColorValue`	The color in every format.
`updateColor`	`(hsva: HSVA) => void`	Set the color from an HSVA value (used by sliders/area).
`setFromString`	`(color: string) => ColorValue \| null`	Parse and set from any color string.
`startDrag`	`() => void`	Mark a drag as begun (gates onChangeComplete).
`endDrag`	`() => void`	End a drag; fires onChangeComplete with the final color.
`isDragging`	`RefObject<boolean>`	Whether a drag is currently in progress.

usePointerDrag

The drag primitive behind the color area and sliders. Reports normalized 0–1 coordinates and manages the document-level pointer listeners for you.

const { containerRef, handlePointerDown } = usePointerDrag(
  ({ x, y }) => {
    // x, y are 0..1 within the element
  },
  onStart,
  onEnd,
);

<div ref={containerRef} onPointerDown={handlePointerDown} />

useDebounce

A tiny generic debounce — handy for throttling expensive work (persisting, network calls) as the color changes.

const debounced = useDebounce(color, 200);

useEffect(() => {
  save(debounced); // runs 200ms after the last change
}, [debounced]);