Color Picker

A color picker component with swatches, sliders, and input field.

vu-color-picker · @velkin/react/color-picker

Copy page

Import

React

npm i @velkin/react

import { VuColorPicker } from "@velkin/react/color-picker";

Examples

API

Props

Prop	Type	Default	Description
value	`string`	"#3b82f6"	Selected color as hex, rgb(), hsl(), or a named CSS color. Default: `"#3b82f6"`.
format	VuColorPickerFormat	"hex"	Text field and emitted string format. Default: `"hex"`.
showalpha	`boolean`	—	Renders the alpha slider (`showalpha` attr). Default: `false`.
showformat	`boolean`	—	Renders the hex / rgb / hsl format `<select>` (`showformat` attr). Default: `true`.
swatches	`string[]`	[]	Optional preset palette of CSS color strings.
label	`string`	""	Accessible name forwarded to area, sliders, and input.
formatlabel	`string`	—	Accessible name for the format `<select>` (`formatlabel` prop).
swatcheslabel	`string`	—	Accessible name for the preset swatch list (`swatcheslabel` prop).
trigger	VuColorPickerTrigger	"inline"	`inline` panel or `swatch` popover opener. Default: `"inline"`.
placement	VuColorPickerPlacement	"bottom-start"	Popover placement when `trigger="swatch"`. Default: `"bottom-start"`.
open	`boolean`	false	Popover open state when `trigger="swatch"`. Default: `false`.
planecolorspace	VuColorAreaColorSpace	—	2D pad color model (`planecolorspace` attr). Default: `"hsb"`.
planexchannel	VuColorAreaChannel	—	Horizontal pad axis (`planexchannel` attr). Default: `"saturation"`.
planeychannel	VuColorAreaChannel	—	Vertical pad axis (`planeychannel` attr). Default: `"brightness"`.
planeshowdots	`boolean`	—	Passes `showdots` to `<vu-color-area>` (`planeshowdots` attr). Default: `false`.
showarea	`boolean`	—	Renders the 2D color pad (`showarea` attr). Default: `true`.
showhueslider	`boolean`	—	Renders the hue gradient slider (`showhueslider` attr). Default: `true`.
showinput	`boolean`	—	Renders the text color field (`showinput` attr). Default: `true`.
showpreview	`boolean`	—	Renders the live preview chip (`showpreview` attr). Default: `true`.
sliderorientation	VuColorSliderOrientation	—	Hue and alpha slider axis (`sliderorientation` attr). Default: `"horizontal"`.
name	`string`	—	Form field name for submit.
defaultvalue	`string`	—	Value restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks popover and input.
readonly	`boolean`	—	Focusable but value cannot be edited.
required	`boolean`	—	Blocks valid submit when empty.
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
showAlpha	`boolean`	false	Renders the alpha slider (`showalpha` attr).
showFormat	`boolean`	true	Renders the format `<select>` (`showformat` attr).
formatLabel	`string`	""	Accessible name for the format `<select>`.
swatchesLabel	`string`	""	Accessible name for the preset swatch list.
planeColorSpace	VuColorAreaColorSpace	"hsb"	2D pad color model (`planecolorspace` attr).
planeXChannel	VuColorAreaChannel	"saturation"	Horizontal pad axis (`planexchannel` attr).
planeYChannel	VuColorAreaChannel	"brightness"	Vertical pad axis (`planeychannel` attr).
planeShowDots	`boolean`	false	Passes `showdots` to `<vu-color-area>` (`planeshowdots` attr).
showArea	`boolean`	true	Renders the 2D color pad (`showarea` attr).
showHueSlider	`boolean`	true	Renders the hue slider (`showhueslider` attr).
showInput	`boolean`	true	Renders the text color field (`showinput` attr).
showPreview	`boolean`	true	Renders the live preview chip (`showpreview` attr).
sliderOrientation	VuColorSliderOrientation	"horizontal"	Hue and alpha slider axis (`sliderorientation` attr).
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-input	VuColorPickerChangeDetail	Live value while dragging or typing.
vu-change	VuColorPickerChangeDetail	Committed value on pointer up, blur, or swatch pick.
—	`—`	{CustomEvent<{ open: boolean }>} vu-open-change - When `open` changes (`trigger="swatch"`).
vu-open	CustomEvent	Popover opened (`trigger="swatch"`).
vu-close	CustomEvent	Popover closed (`trigger="swatch"`).
vu-invalid	CustomEvent	When validation messages are recomputed while `validationActive`.

Slots

Slot	Description
error	Replaces default validation message list when assigned.

CSS parts

Part	Description
base	Picker body wrapper (area, sliders, input, swatches).
sliders	Hue and optional alpha slider group.
row	Preview chip, text input, and format toggle row.
preview	Live color preview chip.
input	Text input that round-trips the value.
format	Hex / rgb / hsl format `<select>`.
swatches	Preset swatch list container.
trigger	Swatch button when `trigger="swatch"`.
popover	Popover panel when `trigger="swatch"`.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.
field	Column that stacks the picker and optional error.

Methods

Method	Description
show	- Opens the swatch popover; no-op when `trigger="inline"`.
hide	- Closes the swatch popover; no-op when `trigger="inline"`.
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
VuColorAreaChannel	`"hue" \| "saturation" \| "brightness" \| "lightness" \| "red" \| "green" \| "blue"`
VuColorAreaColorSpace	`"hsb" \| "hsl" \| "rgb"`
VuColorPickerChangeDetail	`{ value: string; hex: string; hsv: HSV; hsl: HSL; rgb: RGB; alpha: number; }`
VuColorPickerFormat	`"hsl" \| "rgb" \| "hex"`
VuColorPickerPlacement	`"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"`
VuColorPickerTrigger	`"inline" \| "swatch"`
VuColorSliderOrientation	`"horizontal" \| "vertical"`

Import

React

API

Props

Prop	Type	Default	Description
value	`string`	"#3b82f6"	Selected color as hex, rgb(), hsl(), or a named CSS color. Default: `"#3b82f6"`.
format	VuColorPickerFormat	"hex"	Text field and emitted string format. Default: `"hex"`.
showalpha	`boolean`	—	Renders the alpha slider (`showalpha` attr). Default: `false`.
showformat	`boolean`	—	Renders the hex / rgb / hsl format `<select>` (`showformat` attr). Default: `true`.
swatches	`string[]`	[]	Optional preset palette of CSS color strings.
label	`string`	""	Accessible name forwarded to area, sliders, and input.
formatlabel	`string`	—	Accessible name for the format `<select>` (`formatlabel` prop).
swatcheslabel	`string`	—	Accessible name for the preset swatch list (`swatcheslabel` prop).
trigger	VuColorPickerTrigger	"inline"	`inline` panel or `swatch` popover opener. Default: `"inline"`.
placement	VuColorPickerPlacement	"bottom-start"	Popover placement when `trigger="swatch"`. Default: `"bottom-start"`.
open	`boolean`	false	Popover open state when `trigger="swatch"`. Default: `false`.
planecolorspace	VuColorAreaColorSpace	—	2D pad color model (`planecolorspace` attr). Default: `"hsb"`.
planexchannel	VuColorAreaChannel	—	Horizontal pad axis (`planexchannel` attr). Default: `"saturation"`.
planeychannel	VuColorAreaChannel	—	Vertical pad axis (`planeychannel` attr). Default: `"brightness"`.
planeshowdots	`boolean`	—	Passes `showdots` to `<vu-color-area>` (`planeshowdots` attr). Default: `false`.
showarea	`boolean`	—	Renders the 2D color pad (`showarea` attr). Default: `true`.
showhueslider	`boolean`	—	Renders the hue gradient slider (`showhueslider` attr). Default: `true`.
showinput	`boolean`	—	Renders the text color field (`showinput` attr). Default: `true`.
showpreview	`boolean`	—	Renders the live preview chip (`showpreview` attr). Default: `true`.
sliderorientation	VuColorSliderOrientation	—	Hue and alpha slider axis (`sliderorientation` attr). Default: `"horizontal"`.
name	`string`	—	Form field name for submit.
defaultvalue	`string`	—	Value restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks popover and input.
readonly	`boolean`	—	Focusable but value cannot be edited.
required	`boolean`	—	Blocks valid submit when empty.
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
showAlpha	`boolean`	false	Renders the alpha slider (`showalpha` attr).
showFormat	`boolean`	true	Renders the format `<select>` (`showformat` attr).
formatLabel	`string`	""	Accessible name for the format `<select>`.
swatchesLabel	`string`	""	Accessible name for the preset swatch list.
planeColorSpace	VuColorAreaColorSpace	"hsb"	2D pad color model (`planecolorspace` attr).
planeXChannel	VuColorAreaChannel	"saturation"	Horizontal pad axis (`planexchannel` attr).
planeYChannel	VuColorAreaChannel	"brightness"	Vertical pad axis (`planeychannel` attr).
planeShowDots	`boolean`	false	Passes `showdots` to `<vu-color-area>` (`planeshowdots` attr).
showArea	`boolean`	true	Renders the 2D color pad (`showarea` attr).
showHueSlider	`boolean`	true	Renders the hue slider (`showhueslider` attr).
showInput	`boolean`	true	Renders the text color field (`showinput` attr).
showPreview	`boolean`	true	Renders the live preview chip (`showpreview` attr).
sliderOrientation	VuColorSliderOrientation	"horizontal"	Hue and alpha slider axis (`sliderorientation` attr).
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-input	VuColorPickerChangeDetail	Live value while dragging or typing.
vu-change	VuColorPickerChangeDetail	Committed value on pointer up, blur, or swatch pick.
—	`—`	{CustomEvent<{ open: boolean }>} vu-open-change - When `open` changes (`trigger="swatch"`).
vu-open	CustomEvent	Popover opened (`trigger="swatch"`).
vu-close	CustomEvent	Popover closed (`trigger="swatch"`).
vu-invalid	CustomEvent	When validation messages are recomputed while `validationActive`.

Slots

Slot	Description
error	Replaces default validation message list when assigned.

CSS parts

Part	Description
base	Picker body wrapper (area, sliders, input, swatches).
sliders	Hue and optional alpha slider group.
row	Preview chip, text input, and format toggle row.
preview	Live color preview chip.
input	Text input that round-trips the value.
format	Hex / rgb / hsl format `<select>`.
swatches	Preset swatch list container.
trigger	Swatch button when `trigger="swatch"`.
popover	Popover panel when `trigger="swatch"`.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.
field	Column that stacks the picker and optional error.

Methods

Method	Description
show	- Opens the swatch popover; no-op when `trigger="inline"`.
hide	- Closes the swatch popover; no-op when `trigger="inline"`.
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
VuColorAreaChannel	`"hue" \| "saturation" \| "brightness" \| "lightness" \| "red" \| "green" \| "blue"`
VuColorAreaColorSpace	`"hsb" \| "hsl" \| "rgb"`
VuColorPickerChangeDetail	`{ value: string; hex: string; hsv: HSV; hsl: HSL; rgb: RGB; alpha: number; }`
VuColorPickerFormat	`"hsl" \| "rgb" \| "hex"`
VuColorPickerPlacement	`"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"`
VuColorPickerTrigger	`"inline" \| "swatch"`
VuColorSliderOrientation	`"horizontal" \| "vertical"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse