ColorPicker

colorpicker

Selects colors through saturation and hue controls with HEX, RGB, or HSL output.

Usage

Basic usage

Drag and drop color palette + text input, use defaultValue as the initial color if not controlled.

tsx

<ColorPicker defaultValue="#3b82f6" />

Output format

defaultFormat determines the callback and input box format: hex / rgb / hsl.

tsx

<>
  <ColorPicker defaultValue="#22c55e" defaultFormat="rgb" />
  <ColorPicker defaultValue="#8b5cf6" defaultFormat="hsl" />
</>

Per-frame change vs one commit

onValueChange fires on every drag frame, while onValueCommitted fires once on pointer release, input blur or Enter, and format switching. Attach undo entries and network writes to the latter.

onValueChange · 0onValueCommitted · #3b82f6

tsx

const [changes, setChanges] = useState(0);
const [committed, setCommitted] = useState("#3b82f6");

// Drag the saturation panel: changes keeps climbing, committed updates only on release
<ColorPicker
  defaultValue="#3b82f6"
  onValueChange={() => setChanges((n) => n + 1)}
  onValueCommitted={setCommitted}
/>

Simplification: Hide switcher/input box

showFormatSwitcher / showInput Turn off non-essential parts, leaving only the color plate.

tsx

<>
  <ColorPicker defaultValue="#ef4444" showFormatSwitcher={false} />
  <ColorPicker defaultValue="#06b6d4" showInput={false} />
</>

Disabled

disabled Overlay + Shield interaction.

tsx

<ColorPicker defaultValue="#3b82f6" disabled />

When to use

Use ColorPicker when users need to choose any color from a saturation panel and switch output among HEX, RGB, and HSL. For a small set of presets, use the lighter ColorSwatchPicker.

Import

import { ColorPicker, parseColor, rgbToHex, rgbToHsl, formatColor } from "@hulianui/ui"

Props

Name	Type	Default	Description
value	`string`	-	Controlled color values. Accepts hex / rgb() / hsl() strings, and the internal unified specification is that hex is the single source of truth.
defaultValue	`string`	`"#3b82f6"`	uncontrolled initial value
format	`"hex" \| "rgb" \| "hsl"`	-	Controlled output/display format, input will enter the format controlled mode
defaultFormat	`"hex" \| "rgb" \| "hsl"`	`"hex"`	uncontrolled initial format
disabled	`boolean`	`false`	Disabled: Overlay + Shield interaction
showInput	`boolean`	`true`	Whether to display text input
showFormatSwitcher	`boolean`	`true`	Whether to display the HEX/RGB/HSL format switcher
className	`string`	-	Additional class name for the outer shell.

Events

Event	Type	Description
onValueChange	`(value: string) => void`	Change callback; the argument is a string in the currently selected format, and switching formats also emits. Fires on every frame while the saturation panel or hue bar is dragged
onValueCommitted	`(value: string) => void`	Commit callback, fired once per finished edit, in the same format as `onValueChange`. Triggers: pointer release on the panel, input blur or Enter, and format switching
onFormatChange	`(format: ColorFormat) => void`	Format switching callback

Usage guidelines

onValueChange returns a string in the active format (hex, rgb, or hsl), and changing the format also emits a value. Do not assume callbacks always return hex. Hex remains the internal source of truth.
onValueChange fires on every frame while the saturation panel or hue bar is dragged, so a single drag produces dozens to hundreds of calls. Attach undo entries, network writes, and reflow-triggering work to onValueCommitted instead of debouncing yourself: a debounce cannot know the exact release moment and delays the final value past the moment a popover closes.
onValueCommitted means one edit finished, not "the value changed". Clicking the panel once without dragging still emits on release even though the color never moved. Compare against the previously received value if you need deduplication.
pointercancel, meaning the drag was interrupted by the system or another gesture, does not emit onValueCommitted. Keep the last committed value in that case, and never persist a mid-drag onValueChange value as final.
A controlled value may be any supported hex, rgb(), or hsl() string. The component normalizes it to hex for rendering and converts it back to the selected format when emitting changes.
A controlled value combined with only an onValueCommitted listener freezes the panel: nothing writes value back during the drag, so the picker cannot move. For commit-only usage switch to the uncontrolled defaultValue, and remount with key when the external value has to be followed.

SecretField · Combobox · Listbox · Mentions · InputOTP · Rating

Playground

FormatDisplay format switcherShow input boxDisabled

#3b82f6

<ColorPicker defaultValue="#3b82f6" />

Usage

Basic usage

Drag and drop color palette + text input, use defaultValue as the initial color if not controlled.

tsx

<ColorPicker defaultValue="#3b82f6" />

Output format

defaultFormat determines the callback and input box format: hex / rgb / hsl.

tsx

<>
  <ColorPicker defaultValue="#22c55e" defaultFormat="rgb" />
  <ColorPicker defaultValue="#8b5cf6" defaultFormat="hsl" />
</>

Per-frame change vs one commit

onValueChange fires on every drag frame, while onValueCommitted fires once on pointer release, input blur or Enter, and format switching. Attach undo entries and network writes to the latter.

onValueChange · 0onValueCommitted · #3b82f6

tsx

const [changes, setChanges] = useState(0);
const [committed, setCommitted] = useState("#3b82f6");

// Drag the saturation panel: changes keeps climbing, committed updates only on release
<ColorPicker
  defaultValue="#3b82f6"
  onValueChange={() => setChanges((n) => n + 1)}
  onValueCommitted={setCommitted}
/>

Simplification: Hide switcher/input box

showFormatSwitcher / showInput Turn off non-essential parts, leaving only the color plate.

tsx

<>
  <ColorPicker defaultValue="#ef4444" showFormatSwitcher={false} />
  <ColorPicker defaultValue="#06b6d4" showInput={false} />
</>

Disabled

disabled Overlay + Shield interaction.

tsx

<ColorPicker defaultValue="#3b82f6" disabled />

Props

Name	Type	Default	Description
value	`string`	-	Controlled color values. Accepts hex / rgb() / hsl() strings, and the internal unified specification is that hex is the single source of truth.
defaultValue	`string`	`"#3b82f6"`	uncontrolled initial value
format	`"hex" \| "rgb" \| "hsl"`	-	Controlled output/display format, input will enter the format controlled mode
defaultFormat	`"hex" \| "rgb" \| "hsl"`	`"hex"`	uncontrolled initial format
disabled	`boolean`	`false`	Disabled: Overlay + Shield interaction
showInput	`boolean`	`true`	Whether to display text input
showFormatSwitcher	`boolean`	`true`	Whether to display the HEX/RGB/HSL format switcher
className	`string`	-	Additional class name for the outer shell.

Events

Event	Type	Description
onValueChange	`(value: string) => void`	Change callback; the argument is a string in the currently selected format, and switching formats also emits. Fires on every frame while the saturation panel or hue bar is dragged
onValueCommitted	`(value: string) => void`	Commit callback, fired once per finished edit, in the same format as `onValueChange`. Triggers: pointer release on the panel, input blur or Enter, and format switching
onFormatChange	`(format: ColorFormat) => void`	Format switching callback

Usage guidelines

onValueChange returns a string in the active format (hex, rgb, or hsl), and changing the format also emits a value. Do not assume callbacks always return hex. Hex remains the internal source of truth.

onValueChange fires on every frame while the saturation panel or hue bar is dragged, so a single drag produces dozens to hundreds of calls. Attach undo entries, network writes, and reflow-triggering work to onValueCommitted instead of debouncing yourself: a debounce cannot know the exact release moment and delays the final value past the moment a popover closes.

onValueCommitted means one edit finished, not "the value changed". Clicking the panel once without dragging still emits on release even though the color never moved. Compare against the previously received value if you need deduplication.

pointercancel, meaning the drag was interrupted by the system or another gesture, does not emit onValueCommitted. Keep the last committed value in that case, and never persist a mid-drag onValueChange value as final.

A controlled value may be any supported hex, rgb(), or hsl() string. The component normalizes it to hex for rendering and converts it back to the selected format when emitting changes.

A controlled value combined with only an onValueCommitted listener freezes the panel: nothing writes value back during the drag, so the picker cannot move. For commit-only usage switch to the uncontrolled defaultValue, and remount with key when the external value has to be followed.

Usage

Basic usage

Output format

Per-frame change vs one commit

Simplification: Hide switcher/input box

Disabled

When to use

Import

Props

Events

Usage guidelines

Related

Playground

Usage

Basic usage

Output format

Per-frame change vs one commit

Simplification: Hide switcher/input box

Disabled

When to use

Import

Props

Events

Usage guidelines

Related

Playground