Skip to content

Combobox

Search a list of options and select one or more values.

Demos

Size
Variant

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Installation

Complete the shared installation. Copy Combobox.vue and index.ts into app/components/ui/combobox/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm
variantoutline, soft, bareoutline

Props

PropTypeDefaultDescription
optionsComboboxOption[]requiredOptions rendered in the listbox.
valueKeystring—Object key used as option value.
labelKeystring"label"Object key used as option label.
descriptionKeystring"description"Object key used as description.
disabledKeystring"disabled"Object key used as disabled state.
placeholderstring—Input placeholder.
multiplebooleanfalseEnables multi-select.
nullableValuestring""Submitted empty value.
idstringfield idInput id.
namestringfield nameForm field name for hidden selected values.
requiredbooleanfalseRequired state.
disabledbooleanfalseDisables input and options.
readOnlybooleanfalseKeeps value readable but prevents opening, search, and selection changes.
invalidbooleanfalseSets invalid attrs.
loopbooleantrueArrow navigation wraps.
filterablebooleantrueEnables client filtering and aria-autocomplete="list".
filter(option, search) => booleanlabel contains searchCustom filter.
isEqual(a, b) => booleanObject.isValue comparator, useful for recreated object values.
serializeValue(value) => stringstring/JSONSerializes values for native form submission.
loadingbooleanfalseShows loading slot.
emptyLabelstring"No results found."Default empty text.
resetSearchOnBlurbooleanfalseClears search on blur.
resetSearchOnSelectbooleantrueClears search after selection.
openOnFocusbooleantrueOpens when input receives focus.
openOnClickbooleantrueOpens when input is clicked.
openOnInputbooleantrueOpens when search text changes.
clearablebooleanfalseRenders clear button when filled.
creatablebooleanfalseShows create row for unmatched search.
createLabel(search) => stringCreate “…”Formats default create row.
highlightOnHoverbooleantruePointer hover updates highlight.
side"top" | "bottom""bottom"Popup side.
align"start" | "center" | "end""start"Popup alignment.
sideOffsetnumber6Popup gap in pixels.
ariaLabelstring—Accessible label.
ariaLabelledbystring—Accessible label id.
ariaDescribedbystringfield description/errorDescription ids.
uiComboboxUi—Classes for structural parts.

Slots

SlotPropsDescription
optionoption, value, label, description, isSelected, isHighlighted, isDisabled, selectCustom option row.
[option.slot]Same as optionPer-option renderer.
tagoption, value, removeSelected tag content.
clear—Clear-button content.
createsearch, createCreate-row content.
group-labeloption, labelCustom group label row.
empty—Empty state.
loading—Loading state.

Events

EventPayloadDescription
open-change(open, details)Fired before popup opens/closes.
value-change(value, details)Fired before selected value changes.
search-change(value, details)Fired before search text changes.
create(search, details)Requests creation of unmatched search text.

Keyboard

KeyBehavior
ArrowDown / ArrowUpOpen popup and move highlight.
EnterSelect highlighted option or request creation for unmatched text.
Home / EndMove to first/last enabled visible option.
EscapeClose popup.