# Color picker

> A colour field with a real saturation surface, kinetic hue and opacity rails, typed hex, RGB or HSL, and swatches that stay in sync.

Native colour inputs hand the most expressive control in a product to the operating system. This picker keeps the whole experience in your theme: a colour field grows into a saturation and lightness surface, hue and opacity move on direct, pointer-accurate rails, and a swatch, typed value or arrow key glides the thumbs to the new colour (a drag follows the pointer exactly). Transparent colours sit on a checkerboard so opacity reads as opacity. Hex, RGB and HSL can be switched without losing alpha, while every gesture and keyboard change reports a plain CSS colour string.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/color-picker.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/color-picker
- Registry item (source): https://hairlineui.com/r/color-picker.json

## Usage

```tsx
import { ColorPicker } from "@/components/color-picker";

<ColorPicker
  label="Brand colour"
  value={color}
  onValueChange={setColor}
  format="hex"
  alpha
  swatches={["#305DDE", "#7C3AED", "#059669"]}
/>
```

## A live brand preview

The value is an ordinary CSS colour string, so it can drive a preview, a CSS variable or a server-saved theme without another adapter.

```tsx
"use client";

import * as React from "react";
import { ColorPicker } from "@/components/color-picker";

export function BrandSettings() {
  const [color, setColor] = React.useState("#305DDE");

  return (
    <div className="space-y-4">
      <ColorPicker
        label="Accent"
        name="accent"
        value={color}
        onValueChange={setColor}
        alpha
      />
      <button
        type="button"
        className="rounded-full px-4 py-2 text-white"
        style={{ backgroundColor: color ?? "transparent" }}
      >
        Preview action
      </button>
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue` | `string \| null` | – | A hex, RGB or HSL CSS colour. Null means no selection. |
| `onValueChange` | `(value: string \| null) => void` | – | Reports colour changes in the selected output format. |
| `onValueCommit` | `(value: string \| null) => void` | – | Runs after a gesture, keyboard change, swatch or typed value settles. |
| `format` | `"hex" \| "rgb" \| "hsl"` | `"hex"` | Initial serialisation format; the panel button cycles it. |
| `alpha` | `boolean` | `false` | Shows the opacity rail and preserves the selected alpha. |
| `swatches` | `readonly string[]` | – | Reusable colours shown under the value field. |
| `name` | `string` | – | Submits the formatted colour through a hidden input. |
| `label / hint / error` | `ReactNode` | – | Shared field label, help and external error. |
| `disabled / id / className` | `boolean / string / string` | – | Standard field state and layout customisation. |

## States

- **closed**: A 36px hairline field with the current colour, its formatted value and a chevron.
- **open**: The panel grows from the field edge; its colour surface, rails and swatches share one live value.
- **drag**: The colour thumb follows the pointer directly, with no transition or React render loop in the uncontrolled path.
- **typed error**: An unreadable colour shakes once and keeps the typed text with an example of accepted syntax.
- **swatch**: Picking a swatch glides every thumb to the new colour over 420ms and fades the ring onto the chosen swatch.
- **copied**: The copy icon blurs away while a check draws itself, Copy morphs to Copied (or Failed), then both return.

## What it handles

A colour picker needs two-dimensional pointer gestures, colour-space conversion, alpha, keyboard values and reliable text parsing. This handles them without adopting a colour library.

- **Two-axis colour surface**: Horizontal movement changes saturation and vertical movement changes lightness, with pointer capture outside the surface.
- **Direct gesture rendering**: Thumbs and previews are painted through transforms during a drag; uncontrolled React state settles when the gesture ends.
- **Three CSS formats**: Hex, RGB and HSL parse and serialise in modern CSS syntax, including alpha when the value needs it.
- **Typed values that recover**: Enter or blur applies a valid value; an unreadable value stays in place with a useful error instead of disappearing.
- **Keyboard and forms**: Every surface has slider semantics, arrow keys adjust values, Home and End jump, and a hidden input submits the colour.
- **Swatches and copy**: Project colours show the active match, and Copy reports Copied or Failed without replacing the colour field.

## Replaces

native <input type="color">, react-colorful, colour-space conversion helpers, custom saturation and hue sliders, copy-to-clipboard feedback

## Where it fits

- **Website builders**: Choose section, text and accent colours without leaving the editor.
- **Theme settings**: Set a brand colour and copy the exact value into tokens.
- **Design tools**: Adjust hue, saturation, lightness and opacity in one compact panel.
- **Data visualisation**: Assign consistent series colours with reusable project swatches.

## Notes

- The colour surface exposes saturation and lightness in aria-valuetext; hue and opacity have their own slider values.
- Arrow keys adjust the colour surface by 2%, hue by 2° and opacity by 2%. Shift adjusts hue and opacity by larger steps.
- Escape closes and returns focus to the field. Outside dismissal does not steal focus.
- Reduced motion removes panel travel and swatch scaling; colour changes remain immediate.

License: MIT (https://hairlineui.com/license#components)
