Color Swatch Picker

Overview

Choose a color quickly from a preset palette, useful for theme panels and suggested color selections. SColorSwatchPicker combines the Aria ColorSwatchPickerRoot/Item/ItemSwatch/ItemIndicator primitives (built on the listbox) with the colorSwatchPickerVariants style recipe (6 slots, 6 sizes × 2 shapes).

Use a swatch picker for a compact, clickable preset palette (theme panels, brand colors, suggested colors).

Usage

Features

🧩 Aria/listbox based — built on the listbox primitives with role="listbox"/option, roving focus and selection
🎨 Preset palette — pass colors as an array; each renders a ColorSwatch with a check indicator
🔘 Single/multiple — multiple (via the listbox M generic) selects one or many values
✅ Indicator — an indicator slot (default lucide:check) marks the active swatch
🔵 Shape — shape="square" (default) or "circle"
📐 6 sizes — xs–2xl size; per-slot ui overrides
🧩 Custom content — the default slot (when no colors) and swatch/indicator slots for full control

Component family

SColorSwatchPicker (styled) — the entry wrapper; colorSwatchPickerVariants recipe with dynamic slot forwarding
ColorSwatchPickerCompact (Aria) — the aggregated composite; iterates colors into items with swatch + indicator
ColorSwatchPickerRoot (Aria) — the listbox root (modelValue, multiple)
ColorSwatchPickerItem (Aria) — a selectable swatch option (role="option")
ColorSwatchPickerItemSwatch (Aria) — the swatch (ColorSwatchCompact base)
ColorSwatchPickerItemIndicator (Aria) — the selection check indicator

Demo

Basic

100%

#7c3aed

API

Aria Layer

ColorSwatchPicker

19 Props5 Emits

Props

Prop	Type	Default	Description
class	ClassValue	—	Additional class names applied to the root element.
size	ThemeSize	—	Visual size of the component.
ui	Partial<ColorSwatchPickerExtendedUi>	—	Per-slot class overrides for the component.
shape	ColorSwatchPickerShape	—	Shape of the component.
colors	string[]	—	Colors.
itemProps	Omit<ColorSwatchPickerItemProps, 'value'>	—	Properties forwarded to the item element.
indicatorProps	ColorSwatchPickerItemIndicatorProps	—	Properties forwarded to the indicator element.
swatchProps	ColorSwatchPickerItemSwatchProps	—	Properties forwarded to the swatch element.
orientation	DataOrientation	—	The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down)
dir	Direction	—	The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
disabled	boolean	—	When `true`, prevents the user from interacting with listbox
highlightOnHover	boolean	—	When `true`, hover over item will trigger highlight
modelValue	string \| string[]	—	The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model`
defaultValue	string \| string[]	—	The default value of the selected item(s). Use this when you need to set the initial state of the items.
multiple	boolean	—	Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`.
clearable	boolean	—	Whether selected item can be cleared when `multiple` is false.
selectionBehavior	SelectionBehavior	'toggle'	How multiple selection should behave in the collection.
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 \| string[]	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	Event handler when highlighted element changes.
entryFocus	CustomEvent<any>	Event handler called when container is being focused. Can be prevented.
leave	Event	Event handler called when the mouse leave the container
select	SelectEvent<string>	Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`.

ColorSwatchPickerCompact<M>

15 Props5 Emits3 Slots

Props

Prop	Type	Default	Description
colors	string[]	—	Colors.
itemProps	Omit<ColorSwatchPickerItemProps, 'value'>	—	Properties forwarded to the item element.
indicatorProps	ColorSwatchPickerItemIndicatorProps	—	Properties forwarded to the indicator element.
swatchProps	ColorSwatchPickerItemSwatchProps	—	Properties forwarded to the swatch element.
orientation	DataOrientation	—	The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down)
dir	Direction	—	The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
disabled	boolean	—	When `true`, prevents the user from interacting with listbox
highlightOnHover	boolean	—	When `true`, hover over item will trigger highlight
modelValue	(M extends true ? string[] : string)	—	The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model`
defaultValue	(M extends true ? string[] : string)	—	The default value of the selected item(s). Use this when you need to set the initial state of the items.
multiple	M	—	Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`.
clearable	boolean	—	Whether selected item can be cleared when `multiple` is false.
selectionBehavior	SelectionBehavior	'toggle'	How multiple selection should behave in the collection.
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	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	Event handler when highlighted element changes.
entryFocus	CustomEvent<any>	Event handler called when container is being focused. Can be prevented.
leave	Event	Event handler called when the mouse leave the container
select	SelectEvent<string>	Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`.

Slots

Slot Name	Parameters	Description
default	ColorSwatchPickerCompactSlotProps<M>	Custom content rendered when colors are not provided.
swatch	ColorSwatchPickerCompactColorSlotProps	Custom content rendered inside each swatch.
indicator	ColorSwatchPickerCompactColorSlotProps	Custom content rendered inside each indicator.

ColorSwatchPickerCompactColor

ColorSwatchPickerItem

4 Props1 Emits

Props

Prop	Type	Default	Description
value	string	—	The value given as data when submitted with a `name`.
disabled	boolean	—	When `true`, prevents the user from interacting with the item.
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`

Emits

Emit Name	Parameters	Description
select	SelectEvent<string>	Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`.

ColorSwatchPickerItemIndicator

2 Props

Props

Prop	Type	Default	Description
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`

ColorSwatchPickerItemSwatch

6 Props

Props

Prop	Type	Default	Description
checkerProps	ColorSwatchCheckerProps	—	Props for the checker element of the ColorSwatch component.
fillProps	ColorSwatchFillProps	—	Props for the fill element of the ColorSwatch component.
color	import("@soybeanjs/colord").AnyColor	—	Theme color of the component.
label	string	—	Label text rendered by the component.
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`

ColorSwatchPickerRoot<M>

11 Props4 Emits

Props

Prop	Type	Default	Description
orientation	DataOrientation	—	The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down)
dir	Direction	—	The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
disabled	boolean	—	When `true`, prevents the user from interacting with listbox
highlightOnHover	boolean	—	When `true`, hover over item will trigger highlight
modelValue	(M extends true ? string[] : string)	—	The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model`
defaultValue	(M extends true ? string[] : string)	—	The default value of the selected item(s). Use this when you need to set the initial state of the items.
multiple	M	—	Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`.
clearable	boolean	—	Whether selected item can be cleared when `multiple` is false.
selectionBehavior	SelectionBehavior	'toggle'	How multiple selection should behave in the collection.
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	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	Event handler when highlighted element changes.
entryFocus	CustomEvent<any>	Event handler called when container is being focused. Can be prevented.
leave	Event	Event handler called when the mouse leave the container

Notes

Architecture and benchmark differences

ColorSwatchPickerCompact owns the palette iteration (item + swatch + indicator) while every primitive stays style-free and only the UI wrapper injects the colorSwatchPickerVariants classes. This mirrors radix-ui-color/shadcn-ui headless split, built on the shared listbox primitives. Ant Design, Element Plus, Mantine and Naive UI ship a single color-picker with a preset row; VeanUI exposes a standalone listbox-based swatch picker with single/multiple selection, a check indicator, shape/size control and full slot overrides.

Capability	VeanUI	shadcn/ui	Ant Design	Element Plus	Mantine	Naive UI
Aria/listbox based	✅	✅	—	—	—	—
Single/multiple	✅	✅	✅	✅	✅	—
Check indicator	✅	✅	—	—	—	—
Roving focus	✅	✅	—	—	—	—
Shape (square/circle)	✅	✅	✅	✅	✅	—
Sizes (6)	✅	—	—	—	—	—

— = unsupported or a different interaction model.

Cautions

colors is an array of color strings; each renders an ColorSwatch option with a check indicator on the active value.
Selection emits update:modelValue (single: a string; multiple: an array) and select.
Provide indicator/swatch slots to customize the check mark and swatch content; use the default slot to render fully custom content when colors is empty.
shape switches between square (rounded-md) and circle (rounded-full).
Built on the listbox primitives, so keyboard/roving-focus behavior follows the listbox contract.

Roadmap

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

FAQ

How do I build a swatch picker?

Pass colors and bind model-value:

<SColorSwatchPicker v-model:model-value="color" :colors="['#7c3aed', '#06b6d4', '#10b981']" />

How do I allow multiple selection?

Use multiple (the value becomes an array):

<SColorSwatchPicker v-model:model-value="colors" multiple :colors="palette" />

How do I make the swatches circular?

Set shape="circle":

<SColorSwatchPicker v-model:model-value="color" :colors="palette" shape="circle" />

How do I customize the indicator?

Use the indicator slot:

<SColorSwatchPicker v-model:model-value="color" :colors="palette">
  <template #indicator>✓</template>
</SColorSwatchPicker>

Quick jump

Related components

Color Swatch Picker

Overview

Usage

Features

Component family

Demo

Basic

API

Aria Layer

ColorSwatchPicker

Props

Emits

ColorSwatchPickerCompact<M>

Props

Emits

Slots

ColorSwatchPickerCompactColor

ColorSwatchPickerItem

Props

Emits

ColorSwatchPickerItemIndicator

Props

ColorSwatchPickerItemSwatch

Props

ColorSwatchPickerRoot<M>

Props

Emits

Notes

Architecture and benchmark differences

Cautions

Roadmap

FAQ

How do I build a swatch picker?

How do I allow multiple selection?

How do I make the swatches circular?

How do I customize the indicator?

Changelog

v0.19.0

Fix