Color Picker
FreeA 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-pickerPlayground
Color picker
Saved colours
Installation
npx wunderui-cli add color-pickerWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
ColorPicker,
ColorPickerTrigger,
} from "@/components/wunderui/color-picker"
import type { ColorPickerProps } from "@/components/wunderui/color-picker"Then use it:
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
- Radio Button Group for a choice from a few fixed colours
- Cell Color Picker for a compact swatch inside a Data Table cell
- Input for a colour that is only ever typed as text
Header
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
Brand colour
Saved colours
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
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
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.
- TaborShift+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.
- 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.
- 1Optional
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.
- 2
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.
- 3
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.
- 4
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.
- 5
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "spectrum" | "grid" | "spectrum" | (the default) picks in a saturation and brightness area; picks from a grid of swatches. |
| value | string | — | The colour as , to control it. Update it in . |
| defaultValue | string | "#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. |
| alpha | number | — | The opacity from 0 to 1, to control it. |
| defaultAlpha | number | 1 | The opacity to start with. Defaults to 1. |
| onAlphaChange | (alpha) => void | — | Called with the new opacity. |
| showAlpha | boolean | true | Whether 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. |
| swatches | string[] | — | The saved colours, to control them. |
| defaultSwatches | string[] | DEFAULT_SWATCHES | The 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. |
| title | ReactNode | "Color picker" | The heading of the panel. hides it. Defaults to . |
| onClose | () => void | — | Shows the close button and is called when it is pressed. |
| className | string | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | The colour as , to control it. |
| defaultValue | string | "#555CF3" | The colour to start with. Defaults to . |
| onValueChange | (hex) => void | — | Called with the new colour from the picker in the popover. |
| label | string | "Colour" | The accessible name of the field, followed by the value. Defaults to . |
| pickerProps | Omit<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. |
| open | boolean | — | Whether the popover is open, to control it. |
| defaultOpen | boolean | false | Whether the popover starts open when is not set. |
| onOpenChange | (open) => void | — | Called with the new open state when the popover opens or closes. |
| className | string | — | Extra classes for the field, for example . |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("color-picker")npx wunderui-cli add color-pickerThe full library index for assistants is at /llms.txt.