# Color Picker

Pick a colour: saturation and brightness, hue, opacity, eyedropper, HEX/RGB/HSL values and saved colours — inline or from a trigger field.

- Category: Forms
- Page: https://wunderui.com/components/color-picker
- Tier: Free

## Install

```bash
npx wunderui-cli add color-picker
```

## Import

```tsx
import { ColorPicker, ColorPickerProps, ColorPickerTrigger } from "@/components/wunderui/color-picker"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

export function BrandColour() {
  const [color, setColor] = useState("#555CF3")

  return <ColorPicker value={color} onValueChange={setColor} />
}
```

Expected result: You see a panel with a colour area, a hue and an opacity slider, a value field and nine saved colours. Drag in the area or on a slider and the value follows.

## Usage

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

export function Example() {
  const [color, setColor] = useState("#555CF3")

  return (
    <ColorPicker value={color} onValueChange={setColor} />
  )
}
```

## When to use

### Use Color Picker for

- A brand or accent colour in a settings page, with a preview of what it changes
- A highlight, label or tag colour in an editor, where opacity matters
- Any colour that people may choose freely, including from a value they paste

### Use something else

- [Radio Button Group](https://wunderui.com/components/radio-button-group) for a choice from a few fixed colours
- [Cell Color Picker](https://wunderui.com/components/cell-color-picker) for a compact swatch inside a Data Table cell
- [Input](https://wunderui.com/components/input) for a colour that is only ever typed as text

## Keyboard

The area and both sliders are sliders with one tab stop each. The fields, swatches and buttons are native controls.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus through the close button, the colour area, the eyedropper, the two sliders, the format select, the value fields and the saved colours. |
| `ArrowLeft` or `ArrowRight` | On the colour area: changes saturation by 1 %, and with Shift by 10 %. On a slider: changes the value by 1 %, and with Shift by 10 %. |
| `ArrowUp` or `ArrowDown` | On the colour area: changes brightness by 1 %, and with Shift by 10 %. On a slider: the same as Right and Left. |
| `Home` or `End` | On a slider: goes to 0 % or 100 %. In the swatch grid: goes to the first or the last swatch. |
| `ArrowLeft` or `ArrowRight` or `ArrowUp` or `ArrowDown` | In the swatch grid (`variant="grid"`): moves to the next swatch, a row at a time with Up and Down. |
| `Enter` | In a value field: commits the typed value. On a swatch, the plus or the trigger: activates it. |
| `Escape` | In the popover of a trigger: closes it and returns focus to the trigger. |

## Behavior

What the picker does with state, values, formats and motion.

- **Controlled or not:** Value, opacity, format and swatches can each be controlled with a change handler, or kept by the picker from a default.
- **The value:** The colour is a hex string in capitals. Opacity is separate, from 0 to 1, so the hex never carries an alpha pair.
- **Hue stays:** The picker keeps hue, saturation and brightness itself. At zero saturation or brightness a colour has no hue, so the hue slider stays put instead of jumping to red.
- **Formats:** The select switches the fields between HEX, RGB and HSL without changing the colour. An unreadable value is dropped when you leave the field, and an empty field returns to the last valid value.
- **Eyedropper:** The eyedropper picks a colour from anywhere on the screen. It exists in Chromium browsers only, so elsewhere the button is left out.
- **Saved colours:** The plus button adds the current colour to the row, unless it is already there. Choosing a swatch sets the colour.
- **Trigger:** The field opens the picker in a popover 8 px below it. A popover that is open from the start does not pull focus on load, but one opened by pointer or keyboard takes it.
- **Motion:** The popover fades and scales in, then fades out faster. The trigger chevron turns and the ring of a saved colour changes quickly.
- **Reduced motion:** With reduced motion the popover keeps its fade and drops the scale. The panel has no other movement.

## Anatomy

- `ColorPicker`: A 296 px wide card with a title, a colour area, hue and opacity sliders, value fields and saved colours. It holds the colour as a hex string and the opacity from 0 to 1, and it is not a native input.
- `Header`: The title, Color picker by default, and a close button at the right when a close handler is set. Setting the title to null removes the title, and the whole header if there is no close handler.
- `Colour area`: A two-dimensional slider: saturation runs left to right and brightness bottom to top. The grid variant is a grid of greys and nine shades of twelve hues, with arrow keys moving between swatches.
- `Hue and opacity`: Two sliders under the area, with an eyedropper button at the left in browsers that have one. The opacity slider and field can be left out.
- `Value`: A select for the format (HEX, RGB or HSL) and the fields for the value, followed by the opacity in percent. A field commits on Enter or blur, so typing 2 on the way to 255 does not move the colour.
- `Saved colours`: A row of 24 px swatches with a plus button that saves the current colour. The chosen swatch gets a ring in its own colour, and you can set the first set or control the whole list.
- `ColorPickerTrigger`: A field that opens the picker in a popover below it: a swatch, the hex value and a chevron, the size of an Input. The pill shape is a 32 px pill with a colour dot, for a row of presets.
- `Dot`

## Best practices

### Do

- Use ColorPickerTrigger in a form or a settings row. The field shows the colour at rest, and the panel opens only when it is needed.
- Use ColorPicker on the page when the colour is the task, for example an editor with a preview beside it. Judge the colour on real content, not on a bare swatch.
- Hold the colour as a hex string and the opacity as a number, each with its change handler. Leave opacity out where a colour is always opaque.
- Pass the colours of your product as the default swatches, so people start from a palette they should use.
- Give the trigger a label, such as Primary colour. Its accessible name is the label plus the value, because a swatch alone says nothing to a screen reader.

### Don't

- Don't use a native color input. Its panel is the browser's own and cannot carry your tokens, your saved colours or an opacity.
- Don't use a colour as the only information. A picked colour needs its value in text, as the field and the preview line show.
- Don't use it to choose from a short list of fixed colours. A row of Selector Items or a Radio Button Group is quicker and keeps people inside your palette.

## API reference

### ColorPicker

| Prop | Type | Default | Description |
|---|---|---|---|
| alpha | number |  | The opacity from 0 to 1, to control it. |
| className | string |  | Extra classes for the panel. |
| defaultAlpha | number | 1 | The opacity to start with. Defaults to 1. |
| defaultFormat | "hex" \| "rgb" \| "hsl" | "hex" | The format to start with. Defaults to `hex`. |
| defaultSwatches | string[] | DEFAULT_SWATCHES | The saved colours to start with. Defaults to nine library hues. |
| defaultValue | string | "#555CF3" | The colour to start with when the picker keeps its own state. Defaults to `#555CF3`. |
| format | "hex" \| "rgb" \| "hsl" |  | The format of the value fields, `hex`, `rgb` or `hsl`, to control it. |
| onAlphaChange | (alpha: number) => void |  | Called with the new opacity. |
| onClose | () => void |  | Shows the close button and is called when it is pressed. |
| onFormatChange | (format: ColorFormat) => void |  | Called with the new format when the select changes. |
| onSwatchesChange | (swatches: string[]) => void |  | Called with the new list when the plus button saves a colour. |
| onValueChange | (hex: string) => void |  | Called with the new `#RRGGBB` colour while you drag, type or choose a swatch. |
| showAlpha | boolean | true | Whether the opacity slider and field are shown. Defaults to true. |
| swatches | string[] |  | The saved colours, to control them. |
| title | React.ReactNode | "Color picker" | The heading of the panel. `null` hides it. Defaults to `Color picker`. |
| value | string |  | The colour as `#RRGGBB`, to control it. Update it in `onValueChange`. |
| variant | "spectrum" \| "grid" | "spectrum" | `spectrum` (the default) picks in a saturation and brightness area; `grid` picks from a grid of swatches. |

### ColorPickerTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| align | "start" \| "center" \| "end" | "start" | How the popover lines up with the field: `start` (the default), `center` or `end`. |
| className | string |  | Extra classes for the field, for example `w-full`. |
| defaultOpen | boolean | false | Whether the popover starts open when `open` is not set. |
| defaultValue | string | "#555CF3" | The colour to start with. Defaults to `#555CF3`. |
| label | string | "Colour" | The accessible name of the field, followed by the value. Defaults to `Colour`. |
| onOpenChange | (open: boolean) => void |  | Called with the new open state when the popover opens or closes. |
| onValueChange | (hex: string) => void |  | Called with the new colour from the picker in the popover. |
| open | boolean |  | Whether the popover is open, to control it. |
| pickerProps | Omit<ColorPickerProps, "value" \| "defaultValue" \| "onValueChange" \| "onClose"> |  | Everything else the picker takes, such as `alpha`, `format`, `swatches` or `variant`. |
| shape | "default" \| "pill" | "default" | `default` is the Input-sized field with a square swatch; `pill` is a 32 px pill with a colour dot. |
| side | "top" \| "bottom" | "bottom" | Whether the popover opens below (`bottom`, the default) or above (`top`) the field. |
| value | string |  | The colour as `#RRGGBB`, to control it. |

## Examples

### Header: a title, a title with a close button, or none

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

export function Example() {
  const [color, setColor] = useState("#555CF3")

  return (
    <ColorPicker title="Brand colour" value={color} onValueChange={setColor} />
  )
}
```

### Opacity: with the opacity slider, or without

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

export function Example() {
  const [color, setColor] = useState("#555CF3")

  return (
    <ColorPicker showAlpha value={color} onValueChange={setColor} />
  )
}
```

### Saved colours: the default set, or the colours of your product

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

export function Example() {
  const [color, setColor] = useState("#555CF3")

  return (
    <ColorPicker value={color} onValueChange={setColor} />
  )
}
```

### Trigger: a field or a pill that opens the picker

```tsx
import { useState } from "react"
import { ColorPickerTrigger } from "@/components/ui/color-picker"

export function Example() {
  const [color, setColor] = useState("#555CF3")

  return <ColorPickerTrigger label="Brand colour" value={color} onValueChange={setColor} />
}
```

## In context

### Brand colour setting: a labelled field in a settings card

The field shows the colour and opens the picker below it. The preview under the field follows the colour as you pick.

```tsx
import { useState } from "react"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { ColorPickerTrigger } from "@/components/ui/color-picker"
import { Label } from "@/components/ui/label"

export function Example() {
  const [color, setColor] = useState("#555CF3")

  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Brand colour</CardTitle>
        <CardDescription>Buttons, links, focus rings and the first chart series use it.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-2">
        <Label>Primary</Label>
        <ColorPickerTrigger label="Primary colour" className="w-full" value={color} onValueChange={setColor} />
        <p className="text-xs text-text-tertiary">
          Preview: <span className="font-medium" style={{ color }}>View report</span>
        </p>
      </CardContent>
    </Card>
  )
}
```

### Highlight colour: judge the colour and its opacity on real text

The picker sits beside a note. The marker takes the picked colour and opacity, and the line under the note repeats the values.

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

/** "#555CF3" and 0.4 become "rgb(85 92 243 / 0.4)". */
function withOpacity(hex: string, alpha: number): string {
  const channel = (start: number) => parseInt(hex.slice(start, start + 2), 16)
  return `rgb(${channel(1)} ${channel(3)} ${channel(5)} / ${alpha})`
}

export function Example() {
  const [color, setColor] = useState("#FACA4A")
  const [alpha, setAlpha] = useState(0.6)

  return (
    <div className="flex flex-wrap items-start justify-center gap-4">
      <ColorPicker
        title="Highlight colour"
        value={color}
        onValueChange={setColor}
        alpha={alpha}
        onAlphaChange={setAlpha}
      />
      <div className="flex w-72 flex-col gap-3 rounded-xl border border-border bg-card p-4">
        <p className="text-sm text-text-secondary">
          Check the{" "}
          <mark className="rounded-sm px-1 text-foreground" style={{ background: withOpacity(color, alpha) }}>
            pricing page copy
          </mark>{" "}
          with Priya Raman before Friday.
        </p>
        <p className="text-xs text-text-tertiary tabular-nums">
          {color} at {Math.round(alpha * 100)}%
        </p>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("color-picker")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
