Combobox

A combobox component with search, single or multi select, and validation.

vu-combobox · @velkin/react/combobox

Copy page

Import

React

npm i @velkin/react

import { VuCombobox } from "@velkin/react/combobox";

Examples

API

Props

Prop	Type	Default	Description
variant	VuComboboxVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuComboboxTone	"normal"	Neutral chrome weight. Default: `"normal"`.
size	VuComboboxSize	"md"	Field scale. Default: `"md"`.
radius	VuComboboxRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the trigger to the container width. Default: `false`.
name	`string`	—	Form field name. Default: `""`.
defaultValue	`string`	—	Uncontrolled initial value; HTML attribute is `value`. Default: `""`.
formId	`string \| null`	—	ID of an external `<form>`; HTML attribute is `formid`. Default: `null`.
disabled	`boolean`	false	Non-interactive state. Default: `false`.
readonly	`boolean`	false	Read-only; keeps focus without editing. Default: `false`.
required	`boolean`	false	Marks the field required for form validation. Default: `false`.
requiredMessage	`string`	"Selection is required."	Message when `required` fails. Default: `"Selection is required."`.
value	VuComboboxValue	""	Current selection; string or array when `multiple`.
placeholder	`string`	"Select An Option"	Empty-state hint and filter placeholder when `searchable`.
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
options	VuComboboxOption[]	[]	Option list (`string` or `{ label, value }`).
renderer	`null \| (context: VuComboboxRendererContext) => TemplateResult \| string \| null \| undefined`	null	Per-row dropdown renderer; omit for default label.
clearable	`boolean`	false	Shows a clear control when a value is present. Default: `false`.
loading	`boolean`	false	Shows a loading row in the options panel. Default: `false`.
searchable	`boolean`	false	Filter-as-you-type in the field. Default: `false`.
multiple	`boolean`	false	Multi-select chips instead of a single value. Default: `false`.
visibleChips	`number`	2	Max chips shown inline before +N overflow. Default: `2`.
showErrors	`boolean`	false	Renders validation errors below the field. Default: `false`.
addOption	`boolean`	false	Allows creating a new option from the filter query. Default: `false`.
id	`string`	""	Host id; also prefixes internal control ids when set.
ariaLabel	`string`	""	Accessible name when no visible label is present.
validationActive	`boolean`	false	Shows validation affordances after first interaction. Default: `false`.
invalid	`boolean`	false	Reflects validation failure state. Default: `false`.
query	`string`	""	Current field filter for controlled filtering.

Events

Event	Detail	Description
vu-change	VuComboboxChangeDetail	Fired whenever selection changes.
vu-input	VuComboboxInputDetail	Fired when the field filter query changes.
vu-invalid	VuComboboxInvalidDetail	Fired when validation messages are recomputed.
vu-add	VuComboboxAddDetail	Fired when the user confirms adding a new option.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
start	Leading unit or symbol inside the field container.
end	Trailing unit or symbol inside the field container.

CSS parts

Part	Description
field	Column stacking label, control row, hint, and error.
label	Label wired to the trigger.
start	Leading affix wrapper.
end	Trailing affix wrapper.
container	Interactive field trigger (chips, placeholder, actions).
value	Chip + filter input row when `searchable` or `addOption`.
placeholder-label	Placeholder when no value is selected.
clear-button	Clear selection control.
dropdown-button	Chevron toggle control.
dropdown-loading	Loading row in the options panel.
dropdown-loading-indicator	Spinner inside the dropdown loading row.
dropdown-loading-label	Loading copy in the dropdown panel.
chip-container	Multi-select chip row.
chip	Individual chip in multi-select mode.
single-select-chip	Single-select value label.
overflow-chip	+N overflow chip.
remove-chip-icon	Remove icon on chips.
hidden-chips-dropdown	Overflow chip popover panel.
hidden-chip-inner	Row inside the overflow panel.
hidden-chip-label	Label in overflow panel rows.
dropdown	Main options popover panel.
input	Field filter text input when `searchable` or `addOption`.
add-option-icon	Add-new-option affordance in the field.
select-all	Select-all row in multi-select mode.
option	One selectable option row.
option-content	Custom or default label region inside an option row.
highlighted-text	Search-highlighted label text.
no-options	Empty filter message row.
dropdown-scroller	Scrollable options region.
hint	Helper text region.
error-message	Validation error region.
error-line	One default validation string.

Methods

Method	Description
openDropdown	Opens the options panel.
closeDropdown	Closes the options panel.
clearSelection	Clears current selection if allowed.
reset	Resets combobox state and clears validation UI.

Types

Name	Definition
VuComboboxAddDetail	`{ value: string; }`
VuComboboxChangeDetail	`{ value: VuComboboxValue; selectedItems: VuComboboxOption[]; }`
VuComboboxInputDetail	`{ query: string; }`
VuComboboxInvalidDetail	`{ errors: string[]; }`
VuComboboxRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuComboboxRendererFn \| null	`null \| (context: VuComboboxRendererContext) => TemplateResult \| string \| null \| undefined`
VuComboboxSize	`"sm" \| "md" \| "lg"`
VuComboboxTone	`"subtle" \| "normal" \| "strong"`
VuComboboxValue	`string \| string[]`
VuComboboxVariant	`"outline" \| "default" \| "underline"`

Import

React

API

Props

Prop	Type	Default	Description
variant	VuComboboxVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuComboboxTone	"normal"	Neutral chrome weight. Default: `"normal"`.
size	VuComboboxSize	"md"	Field scale. Default: `"md"`.
radius	VuComboboxRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the trigger to the container width. Default: `false`.
name	`string`	—	Form field name. Default: `""`.
defaultValue	`string`	—	Uncontrolled initial value; HTML attribute is `value`. Default: `""`.
formId	`string \| null`	—	ID of an external `<form>`; HTML attribute is `formid`. Default: `null`.
disabled	`boolean`	false	Non-interactive state. Default: `false`.
readonly	`boolean`	false	Read-only; keeps focus without editing. Default: `false`.
required	`boolean`	false	Marks the field required for form validation. Default: `false`.
requiredMessage	`string`	"Selection is required."	Message when `required` fails. Default: `"Selection is required."`.
value	VuComboboxValue	""	Current selection; string or array when `multiple`.
placeholder	`string`	"Select An Option"	Empty-state hint and filter placeholder when `searchable`.
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
options	VuComboboxOption[]	[]	Option list (`string` or `{ label, value }`).
renderer	`null \| (context: VuComboboxRendererContext) => TemplateResult \| string \| null \| undefined`	null	Per-row dropdown renderer; omit for default label.
clearable	`boolean`	false	Shows a clear control when a value is present. Default: `false`.
loading	`boolean`	false	Shows a loading row in the options panel. Default: `false`.
searchable	`boolean`	false	Filter-as-you-type in the field. Default: `false`.
multiple	`boolean`	false	Multi-select chips instead of a single value. Default: `false`.
visibleChips	`number`	2	Max chips shown inline before +N overflow. Default: `2`.
showErrors	`boolean`	false	Renders validation errors below the field. Default: `false`.
addOption	`boolean`	false	Allows creating a new option from the filter query. Default: `false`.
id	`string`	""	Host id; also prefixes internal control ids when set.
ariaLabel	`string`	""	Accessible name when no visible label is present.
validationActive	`boolean`	false	Shows validation affordances after first interaction. Default: `false`.
invalid	`boolean`	false	Reflects validation failure state. Default: `false`.
query	`string`	""	Current field filter for controlled filtering.

Events

Event	Detail	Description
vu-change	VuComboboxChangeDetail	Fired whenever selection changes.
vu-input	VuComboboxInputDetail	Fired when the field filter query changes.
vu-invalid	VuComboboxInvalidDetail	Fired when validation messages are recomputed.
vu-add	VuComboboxAddDetail	Fired when the user confirms adding a new option.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
start	Leading unit or symbol inside the field container.
end	Trailing unit or symbol inside the field container.

CSS parts

Part	Description
field	Column stacking label, control row, hint, and error.
label	Label wired to the trigger.
start	Leading affix wrapper.
end	Trailing affix wrapper.
container	Interactive field trigger (chips, placeholder, actions).
value	Chip + filter input row when `searchable` or `addOption`.
placeholder-label	Placeholder when no value is selected.
clear-button	Clear selection control.
dropdown-button	Chevron toggle control.
dropdown-loading	Loading row in the options panel.
dropdown-loading-indicator	Spinner inside the dropdown loading row.
dropdown-loading-label	Loading copy in the dropdown panel.
chip-container	Multi-select chip row.
chip	Individual chip in multi-select mode.
single-select-chip	Single-select value label.
overflow-chip	+N overflow chip.
remove-chip-icon	Remove icon on chips.
hidden-chips-dropdown	Overflow chip popover panel.
hidden-chip-inner	Row inside the overflow panel.
hidden-chip-label	Label in overflow panel rows.
dropdown	Main options popover panel.
input	Field filter text input when `searchable` or `addOption`.
add-option-icon	Add-new-option affordance in the field.
select-all	Select-all row in multi-select mode.
option	One selectable option row.
option-content	Custom or default label region inside an option row.
highlighted-text	Search-highlighted label text.
no-options	Empty filter message row.
dropdown-scroller	Scrollable options region.
hint	Helper text region.
error-message	Validation error region.
error-line	One default validation string.

Methods

Method	Description
openDropdown	Opens the options panel.
closeDropdown	Closes the options panel.
clearSelection	Clears current selection if allowed.
reset	Resets combobox state and clears validation UI.

Types

Name	Definition
VuComboboxAddDetail	`{ value: string; }`
VuComboboxChangeDetail	`{ value: VuComboboxValue; selectedItems: VuComboboxOption[]; }`
VuComboboxInputDetail	`{ query: string; }`
VuComboboxInvalidDetail	`{ errors: string[]; }`
VuComboboxRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuComboboxRendererFn \| null	`null \| (context: VuComboboxRendererContext) => TemplateResult \| string \| null \| undefined`
VuComboboxSize	`"sm" \| "md" \| "lg"`
VuComboboxTone	`"subtle" \| "normal" \| "strong"`
VuComboboxValue	`string \| string[]`
VuComboboxVariant	`"outline" \| "default" \| "underline"`

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