Color Picker

Overview

A composite color picker that combines a color area, hue/alpha sliders, formatted inputs, and preset swatches, with full oklch editing and output support. SColorPicker composes the Aria color primitives (ColorArea/ColorSlider/ColorField/ColorSwatch/ColorSwatchPicker) inside a popover, with a SegmentCompact for format switching. Nested part styles are unified in colorPickerVariants and forwarded through provideColorPickerUi.

Use a color picker for a full-featured color selection UI (format tabs, saturation plane, hue/alpha sliders, swatch presets and formatted input).

Usage

Features

🧩 Composite Aria — composes ColorArea/ColorSlider/ColorField/ColorSwatchPicker inside a Popover, each style-free
🎛️ Format tabs — SegmentCompact switches hex/rgb/hsl/oklch; update:format reflects the active format
🎨 Full oklch support — colorSpace="oklch" with chroma/lightness area and formatted OKLCH output
🎚️ Hue + alpha sliders — showAlpha toggles the alpha channel slider and field
📝 Formatted field — showFields renders a hex/format input plus an alpha field
🖼️ Preset swatches — showSwatches + swatches render clickable presets (ColorSwatchPicker)
🪟 Popover trigger — open/modal/placement, with a trigger showing the current value
🔒 Disabled — disabled disables all controls
📐 6 sizes — xs–2xl size; per-part ui overrides

Component family

SColorPicker (styled) — the entry wrapper; computes colorPickerVariants and calls provideColorPickerUi
ColorPickerCompact (Aria) — the aggregated composite; wires root, popover, area, sliders, fields and swatches
ColorPickerRoot (Aria) — the shared color state (color/hexValue/displayFormat/areaChannel/setColor/setFormat)
ColorPickerTrigger (Aria) — the button showing the current value
Underlying primitives — ColorAreaCompact, ColorSliderCompact, ColorFieldCompact, ColorSwatchCompact, ColorSwatchPickerCompact, PopoverCompact, SegmentCompact

Demo

Basic

100%

OKLCH

100%

API

Aria Layer

ColorPicker

35 Props12 Emits

Props

Prop	Type	Default	Description
class	ClassValue	—	Additional class names applied to the trigger element.
size	ThemeSize	—	Visual size of the component.
ui	Partial<ColorPickerUi>	—	Per-slot class overrides for the component.
showAlpha	boolean	—	Whether to show an alpha.
showFields	boolean	—	Whether to show a fields.
showSwatches	boolean	—	Whether to show a swatches.
swatches	string[]	—	Swatches.
swatchProps	ColorSwatchCompactProps	—	Properties forwarded to the swatch element.
segmentProps	SegmentCompactProps<T extends SegmentOptionData>	—	Properties forwarded to the segment element.
areaProps	ColorAreaCompactProps	—	Properties forwarded to the area element.
hueSliderProps	ColorSliderCompactProps	—	Properties forwarded to the hue slider element.
alphaSliderProps	ColorSliderCompactProps	—	Properties forwarded to the alpha slider element.
alphaFieldProps	ColorFieldCompactProps	—	Properties forwarded to the alpha field element.
fieldProps	ColorFieldCompactProps	—	Properties forwarded to the field element.
swatchPickerProps	ColorSwatchPickerCompactProps<M extends boolean = false>	—	Properties forwarded to the swatch picker element.
modelValue	import("@soybeanjs/colord").AnyColor	—	Current model value.
defaultValue	import("@soybeanjs/colord").AnyColor	—	Default value.
format	ColorFormat	—	Format.
defaultFormat	ColorFormat	—	Default format.
colorSpace	ColorSpace	—	Color space.
disabled	boolean	—	Whether the component is disabled.
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.
placement	import("@/index").Placement	—	Placement.
showArrow	boolean	—	Whether to show an arrow.
triggerProps	PopoverTriggerProps	—	Properties forwarded to the trigger element.
portalProps	PopperPortalProps	—	Properties forwarded to the portal element.
positionerProps	PopoverPositionerProps	—	Properties forwarded to the positioner element.
popupProps	PopoverPopupProps	—	Properties forwarded to the popup element.
arrowProps	PopperArrowProps	—	Properties forwarded to the arrow element.
closeProps	PopoverCloseProps	—	Properties forwarded to the close element.
dir	Direction	—	—
open	boolean	—	—
defaultOpen	boolean	—	—
modal	boolean	—	—

Emits

Emit Name	Parameters	Description
update:modelValue	string	Emitted when the model value changes.
update:color	NormalizedColor	Emitted when the color value changes.
update:format	ColorFormat	Emitted when the format value changes.
change	string	Emitted when change occurs.
update:open	boolean	Event handler called when the open state of the dialog changes.
escapeKeyDown	KeyboardEvent	Event handler called when the escape key is down. Can be prevented.
pointerDownOutside	PointerDownOutsideEvent	Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.
focusOutside	FocusOutsideEvent	Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented.
openAutoFocus	Event	Event handler called when auto-focusing on open. Can be prevented.
closeAutoFocus	Event	Event handler called when auto-focusing on close. Can be prevented.
placed	—	—

ColorPickerCompact

32 Props12 Emits

Props

Prop	Type	Default	Description
showAlpha	boolean	—	Whether to show an alpha.
showFields	boolean	—	Whether to show a fields.
showSwatches	boolean	—	Whether to show a swatches.
swatches	string[]	—	Swatches.
swatchProps	ColorSwatchCompactProps	—	Properties forwarded to the swatch element.
segmentProps	SegmentCompactProps<T extends SegmentOptionData>	—	Properties forwarded to the segment element.
areaProps	ColorAreaCompactProps	—	Properties forwarded to the area element.
hueSliderProps	ColorSliderCompactProps	—	Properties forwarded to the hue slider element.
alphaSliderProps	ColorSliderCompactProps	—	Properties forwarded to the alpha slider element.
alphaFieldProps	ColorFieldCompactProps	—	Properties forwarded to the alpha field element.
fieldProps	ColorFieldCompactProps	—	Properties forwarded to the field element.
swatchPickerProps	ColorSwatchPickerCompactProps<M extends boolean = false>	—	Properties forwarded to the swatch picker element.
modelValue	import("@soybeanjs/colord").AnyColor	—	Current model value.
defaultValue	import("@soybeanjs/colord").AnyColor	—	Default value.
format	ColorFormat	—	Format.
defaultFormat	ColorFormat	—	Default format.
colorSpace	ColorSpace	—	Color space.
disabled	boolean	—	Whether the component is disabled.
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.
placement	import("@/index").Placement	—	Placement.
showArrow	boolean	—	Whether to show an arrow.
triggerProps	PopoverTriggerProps	—	Properties forwarded to the trigger element.
portalProps	PopperPortalProps	—	Properties forwarded to the portal element.
positionerProps	PopoverPositionerProps	—	Properties forwarded to the positioner element.
popupProps	PopoverPopupProps	—	Properties forwarded to the popup element.
arrowProps	PopperArrowProps	—	Properties forwarded to the arrow element.
closeProps	PopoverCloseProps	—	Properties forwarded to the close element.
dir	Direction	—	—
open	boolean	—	—
defaultOpen	boolean	—	—
modal	boolean	—	—

Emits

Emit Name	Parameters	Description
update:modelValue	string	Emitted when the model value changes.
update:color	NormalizedColor	Emitted when the color value changes.
update:format	ColorFormat	Emitted when the format value changes.
change	string	Emitted when change occurs.
update:open	boolean	Event handler called when the open state of the dialog changes.
escapeKeyDown	KeyboardEvent	Event handler called when the escape key is down. Can be prevented.
pointerDownOutside	PointerDownOutsideEvent	Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.
focusOutside	FocusOutsideEvent	Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented.
openAutoFocus	Event	Event handler called when auto-focusing on open. Can be prevented.
closeAutoFocus	Event	Event handler called when auto-focusing on close. Can be prevented.
placed	—	—

ColorPickerRoot

8 Props4 Emits

Props

Prop	Type	Default	Description
modelValue	import("@soybeanjs/colord").AnyColor	—	Current model value.
defaultValue	import("@soybeanjs/colord").AnyColor	—	Default value.
format	ColorFormat	—	Format.
defaultFormat	ColorFormat	—	Default format.
colorSpace	ColorSpace	—	Color space.
disabled	boolean	—	Whether the component is disabled.
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	string	Emitted when the model value changes.
update:color	NormalizedColor	Emitted when the color value changes.
update:format	ColorFormat	Emitted when the format value changes.
change	string	Emitted when change occurs.

ColorPickerTrigger

4 Props

Props

Prop	Type	Default	Description
type	ButtonType	'button'	The type of the button element. Can be one of 'button', 'submit', or 'reset'.
disabled	boolean	—	Whether the component is disabled.
asChild	boolean	—	Change the default rendered element for the one passed as a child, merging their props and behavior.
as	AsTag \| Component	'div'	The element or component this component should render as. Can be overwrite by `asChild`

Notes

Architecture and benchmark differences

ColorPickerCompact owns the cross-primitive composition (root state + popover + area + sliders + fields + swatches + segment) while every underlying primitive stays style-free. The UI wrapper injects a single colorPickerVariants map through provideColorPickerUi, which remaps aliased slots onto the nested provide*Ui contexts. This mirrors radix-ui-color/shadcn-ui’s headless split. Ant Design, Element Plus, Mantine and Naive UI ship a single styled color-picker with showAlpha/presets props; VeanUI exposes a composite with explicit format tabs, full oklch editing and a size scale.

Capability	VeanUI	shadcn/ui	Ant Design	Element Plus	Mantine	Naive UI
Composite primitives	✅	✅	—	—	—	—
Format tabs	✅	✅	—	—	—	—
Full oklch editing	✅	✅	—	—	—	—
Hue + alpha sliders	✅	✅	✅	✅	✅	—
Preset swatches	✅	✅	✅	✅	✅	—
Sizes (6)	✅	—	—	—	—	—

— = unsupported or a different interaction model.

Cautions

colorSpace (default hsl) drives the area channels and output; defaultFormat/format select the initial/controlled format tab.
showAlpha (default true) adds the alpha slider and alpha field; showFields/showSwatches toggle the input/preset sections.
swatches is an array of preset colors; selecting one emits update:modelValue and change.
The picker opens in a Popover; bind open with v-model:open for controlled usage.
This is the highest-level color component; prefer the individual color-area/color-slider/color-field for embedded, lighter-weight editors.

Roadmap

N/A — color-picker is feature-complete for the current parity set.

FAQ

How do I use a color picker?

Bind model-value and optionally swatches:

<SColorPicker v-model:model-value="color" :swatches="['#7c3aed', '#06b6d4']" />

How do I enable OKLCH editing?

Set color-space and default-format:

<SColorPicker v-model:model-value="color" color-space="oklch" default-format="oklch" />

How do I toggle sections?

Use show-alpha/show-fields/show-swatches:

<SColorPicker v-model:model-value="color" :show-alpha="false" :show-swatches="false" />

How do I control the popover?

Bind open with v-model:open:

<SColorPicker v-model:open="open" v-model:model-value="color" />

Quick jump

Related components

Color Picker

Overview

Usage

Features

Component family

Demo

Basic

OKLCH

API

Aria Layer

ColorPicker

Props

Emits

ColorPickerCompact

Props

Emits

ColorPickerRoot

Props

Emits

ColorPickerTrigger

Props

Notes

Architecture and benchmark differences

Cautions

Roadmap

FAQ

How do I use a color picker?

How do I enable OKLCH editing?

How do I toggle sections?

How do I control the popover?

Changelog

v0.40.0

Fix

v0.31.0

Optimization

Refactor

v0.26.2

Fix

v0.19.0

Fix

v0.15.1

Optimization

v0.15.0

Optimization

Optimization