Color Picker · paneui

Brand accent

Installation

pnpm dlx shadcn@latest add @paneui/color-picker

Usage

import { ColorPicker, ColorPickerArea, ColorPickerContent, ColorPickerHue, ColorPickerTrigger } from "@/components/ui/color-picker"

<ColorPicker>
  <ColorPickerTrigger />
  <ColorPickerContent>
    <ColorPickerArea />
    <ColorPickerHue />
  </ColorPickerContent>
</ColorPicker>

Composition

ColorPicker
├── ColorPickerTrigger
│   └── ColorPickerSwatch (default content)
└── ColorPickerContent
    ├── ColorPickerArea
    ├── ColorPickerHue
    ├── ColorPickerAlpha
    ├── ColorPickerSwatch
    ├── ColorPickerHexInput
    └── ColorPickerPresets
        └── ColorPickerPreset

Examples

With Alpha

Inline

Change vs Commit

Swatch Trigger

Disabled

Keyboard

The area thumb is a 2D slider; arrow keys nudge saturation and brightness 1% (Shift for 10%). Hue and alpha are sliders. The hex field commits on Enter or blur, reverts invalid input, and Escape restores the last value.

Motion

With reduced motion the panel fades instead of growing from the trigger, and the area thumb barely scales while dragging.

See also Wheel Picker and Date Range Picker.

API Reference

Built on the Popover primitive. Only the props this library adds or changes are listed; everything else passes through.

ColorPicker

Colour state plus the popover root. Parts also work inline without trigger and content. Also accepts every prop of Popover.Root.

value: string; Controlled hex colour (#rrggbb or #rrggbbaa).
defaultValue= theme `--primary`: string; Initial colour when uncontrolled. Without it the picker starts on the live --primary token (read after mount; #171717, the default light primary, during server render).
onValueChange: (hex: string) => void; Fires continuously while dragging or typing.
onValueCommit: (hex: string) => void; Fires once when a gesture ends (pointer up, key, hex commit, preset); onValueChange fires continuously while dragging.
alpha= false: boolean; Allow transparency; without it alpha is always 1.
disabled= false: boolean; Disable the trigger and all parts.

Prop	Type	Default	Description
value	string	—	Controlled hex colour (`#rrggbb` or `#rrggbbaa`).
defaultValue	string	theme `--primary`	Initial colour when uncontrolled. Without it the picker starts on the live `--primary` token (read after mount; `#171717`, the default light primary, during server render).
onValueChange	(hex: string) => void	—	Fires continuously while dragging or typing.
onValueCommit	(hex: string) => void	—	Fires once when a gesture ends (pointer up, key, hex commit, preset); `onValueChange` fires continuously while dragging.
alpha	boolean	false	Allow transparency; without it alpha is always 1.
disabled	boolean	false	Disable the trigger and all parts.

ColorPickerTrigger

Raised chip with the swatch and hex. Pass children to replace its content. Also accepts every prop of Popover.Trigger.

showHex= true: boolean; Show the hex label next to the swatch.

Prop	Type	Default	Description
showHex	boolean	true	Show the hex label next to the swatch.

ColorPickerContent

Portal, positioner and 256px popup that grows out of the trigger. Also accepts every prop of Popover.Popup.

align= "start": "start" | "center" | "end"; Trigger edge the panel lines up with.
collisionPadding= 8: number | Padding; Space kept from the viewport edges.
triggerRadius= "var(--radius-lg)": string; Corner radius (CSS length) of the trigger shape the panel morphs from. The default matches ColorPickerTrigger; change it only if you reshape the trigger.

Prop	Type	Default	Description
align	"start" \| "center" \| "end"	"start"	Trigger edge the panel lines up with.
collisionPadding	number \| Padding	8	Space kept from the viewport edges.
triggerRadius	string	"var(--radius-lg)"	Corner radius (CSS length) of the trigger shape the panel morphs from. The default matches `ColorPickerTrigger`; change it only if you reshape the trigger.

ColorPickerArea

Saturation (x) by brightness (y) plane with a draggable thumb. Also accepts every prop of div.

label= the locale's: string; Accessible name of the thumb.

Prop	Type	Default	Description
label	string	the locale's	Accessible name of the thumb.

data-disabled: Present when the picker is disabled.

Data attribute	Description
data-disabled	Present when the picker is disabled.

ColorPickerHue

Hue slider (0–360). Value, range and change handlers are owned by the picker; other props go to the slider root. Also accepts every prop of Slider.Root.

label= the locale's: string; Accessible name of the thumb.
disabled= false: boolean; Disable this slider; the root's disabled also applies.

Prop	Type	Default	Description
label	string	the locale's	Accessible name of the thumb.
disabled	boolean	false	Disable this slider; the root's `disabled` also applies.

ColorPickerAlpha

Opacity slider over a checkerboard. Only meaningful with alpha on the root. Other props go to the slider root, as for ColorPickerHue. Also accepts every prop of Slider.Root.

label= the locale's: string; Accessible name of the thumb.
disabled= false: boolean; Disable this slider; the root's disabled also applies.

Prop	Type	Default	Description
label	string	the locale's	Accessible name of the thumb.
disabled	boolean	false	Disable this slider; the root's `disabled` also applies.

ColorPickerHexInput

Hex field in an inset well; full 6 or 8-digit values apply while typing, and values below full opacity come out as 8-digit hex. Also accepts every prop of input.

aria-label= the locale's: string; Accessible name of the field.

Prop	Type	Default	Description
aria-label	string	the locale's	Accessible name of the field.

ColorPickerSwatch

The current colour over a checkerboard so transparency shows (20px; resize with size-*). Also accepts every prop of span.

ColorPickerPresets

Wrapping group of preset buttons, labelled Presets. Also accepts every prop of div.

ColorPickerPreset

One preset swatch button, an 18px swatch in a 24px hit area, with a ring when aria-pressed (it matches the current colour). Also accepts every prop of button.

value*: string; Hex colour applied on click.
label: string; Accessible name. Defaults to the hex value.

Prop	Type	Default	Description
value*	string	—	Hex colour applied on click.
label	string	—	Accessible name. Defaults to the hex value.

useColorPicker

Current colour and setters for custom parts. Use inside ColorPicker.

hsva: { h: number; s: number; v: number; a: number }; Current colour; h 0–360, others 0–1.
hex: string; Current colour as lowercase hex.
setHsva: (next: Hsva, commit?: boolean) => void; Set the colour; commit also fires onValueCommit.
commit: () => void; Fire onValueCommit with the current colour.
alpha: boolean; Whether alpha is enabled.
disabled: boolean; Whether the picker is disabled.

Prop	Type	Default	Description
hsva	{ h: number; s: number; v: number; a: number }	—	Current colour; `h` 0–360, others 0–1.
hex	string	—	Current colour as lowercase hex.
setHsva	(next: Hsva, commit?: boolean) => void	—	Set the colour; `commit` also fires `onValueCommit`.
commit	() => void	—	Fire `onValueCommit` with the current colour.
alpha	boolean	—	Whether alpha is enabled.
disabled	boolean	—	Whether the picker is disabled.