Skip to content
WunderUI

Color Picker

Free

A panel to pick a colour with an area, hue and opacity sliders, HEX, RGB or HSL values and saved colours, inline or from a trigger.

npx wunderui-cli add color-picker

Playground

Color picker

Saved colours

Installation

bash
npx wunderui-cli add color-picker

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

The panel starts with a title. Add a close handler for a close button on a popup, or remove the title when the page around it already names the control.

Brand colour

Saved colours

Opacity

The opacity slider and field are on by default. Turn them off for colours that are always opaque, such as a brand colour.

Color picker

Saved colours

Saved colours

Saved colours start with nine of the library hues. Pass your own to start with your product colours, and press the plus button to save the current one.

Color picker

Saved colours

Trigger

ColorPickerTrigger is the field that opens the picker in a popover. The default is the size of an Input, and the pill is 32 px with a colour dot for a row of presets.

Keyboard interactions

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

TaborShiftTab
Moves focus through the close button, the colour area, the eyedropper, the two sliders, the format select, the value fields and the saved colours.
ArrowLeftorArrowRight
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 %.
ArrowUporArrowDown
On the colour area: changes brightness by 1 %, and with Shift by 10 %. On a slider: the same as Right and Left.
HomeorEnd
On a slider: goes to 0 % or 100 %. In the swatch grid: goes to the first or the last swatch.
ArrowLeftorArrowRightorArrowUporArrowDown
In the swatch 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 and motion

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

The figure marks the header, colour area, hue slider, value fields and saved colours. ColorPickerTrigger is a separate part that opens the panel in a popover.

Color picker

Saved colours

  • data-slot="color-picker"

    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.

  • Optional

    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.

  • 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.

  • 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.

  • 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.

  • 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.

  • data-slot="color-picker-trigger"Optional

    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.

  • data-slot="color-picker-dot"Optional

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.

  • Do

    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.

  • Do

    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.

  • Do

    Pass the colours of your product as the default swatches, so people start from a palette they should use.

  • Do

    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

    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

    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

One table per part. Neither ColorPicker nor ColorPickerTrigger wraps a primitive, so these tables list every prop.

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.

PropTypeDefaultDescription
variant"spectrum" | "grid""spectrum" (the default) picks in a saturation and brightness area; picks from a grid of swatches.
valuestring—The colour as , to control it. Update it in .
defaultValuestring"#555CF3"The colour to start with when the picker keeps its own state. Defaults to .
onValueChange(hex) => void—Called with the new colour while you drag, type or choose a swatch.
alphanumber—The opacity from 0 to 1, to control it.
defaultAlphanumber1The opacity to start with. Defaults to 1.
onAlphaChange(alpha) => void—Called with the new opacity.
showAlphabooleantrueWhether the opacity slider and field are shown. Defaults to true.
format"hex" | "rgb" | "hsl"—The format of the value fields, , or , to control it.
defaultFormat"hex" | "rgb" | "hsl""hex"The format to start with. Defaults to .
onFormatChange(format) => void—Called with the new format when the select changes.
swatchesstring[]—The saved colours, to control them.
defaultSwatchesstring[]DEFAULT_SWATCHESThe saved colours to start with. Defaults to nine library hues.
onSwatchesChange(swatches) => void—Called with the new list when the plus button saves a colour.
titleReactNode"Color picker"The heading of the panel. hides it. Defaults to .
onClose() => void—Shows the close button and is called when it is pressed.
classNamestring—Extra classes for the panel.

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.

PropTypeDefaultDescription
valuestring—The colour as , to control it.
defaultValuestring"#555CF3"The colour to start with. Defaults to .
onValueChange(hex) => void—Called with the new colour from the picker in the popover.
labelstring"Colour"The accessible name of the field, followed by the value. Defaults to .
pickerPropsOmit<ColorPickerProps, "value" | "defaultValue" | "onValueChange" | "onClose">—Everything else the picker takes, such as , , or .
side"top" | "bottom""bottom"Whether the popover opens below (, the default) or above () the field.
align"start" | "center" | "end""start"How the popover lines up with the field: (the default), or .
shape"default" | "pill""default" is the Input-sized field with a square swatch; is a 32 px pill with a colour dot.
openboolean—Whether the popover is open, to control it.
defaultOpenbooleanfalseWhether the popover starts open when is not set.
onOpenChange(open) => void—Called with the new open state when the popover opens or closes.
classNamestring—Extra classes for the field, for example .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("color-picker")
Installnpx wunderui-cli add color-picker

The full library index for assistants is at /llms.txt.