Combobox

Searchable dropdown that combines a text input with a filterable option list. Built on reka-ui's Combobox — keyboard navigable (arrow keys, enter, escape), supports validation states, and ships with built-in fuzzy filtering.

<Combobox v-model="value" :fuzzy-search="true">
  <ComboboxInput placeholder="Pick a fruit" />
  <ComboboxContent>
    <ComboboxItem v-for="f in fruits" :key="f.value" :value="f.value" :fuzzy-search-data="f.label">
      {{ f.label }}
    </ComboboxItem>
    <ComboboxEmpty>No matches</ComboboxEmpty>
  </ComboboxContent>
</Combobox>

fruits is an array of { value, label }. value (the v-model) is Ref<string | undefined>.

SimpleCombobox — the one-liner

The searchable counterpart of SimpleSelect: a flat { value, label } list, fuzzy search over the labels, nothing to compose. Reach for it for form dropdowns whose list is long enough that typing matters — countries, assets, users. Compose the parts yourself only for grouped lists, custom item bodies, or a create-on-type entry.

import { SimpleCombobox } from '@scaler-tech/aurora/combobox'

<SimpleCombobox v-model="record.country_id" :items="countries" placeholder="Country" />

Prop	Type	Default	Description
v-model	string | number | undefined	—	The chosen item's value — numeric ids stay numbers.
items	{ value: string | number, label: string, disabled?: boolean }[]	—	Required, rendered in array order.
placeholder	string	'Select'	Input placeholder.
emptyText	string	'No results'	Shown when the search matches nothing.
Form state flags	boolean (each)	—	error, success, warning, missing, disabled, readonly.

Every other ComboboxRootProps prop (multiple, disabled, by, …) forwards to the root.

When to reach for a Combobox

• Picking from a long list (>10 options) where search makes the choice tractable
• Asset / building pickers — the user knows part of the name but doesn't want to scroll the full list
• Multi-select scenarios where the full list would be overwhelming to scan without filtering
• Async option lists — the loading state lets you fetch options on demand

When not to use a Combobox

• Short lists (≤6 items) — use a checkbox group, radio group, or a plain native select. The search field is wasted chrome on a small list.
• Single-select with no need for search — use a native <select> instead; less chrome, better mobile keyboard support
• Searching backend-paginated data with debounce — Combobox filters the options it already has. For server-side search, build a custom combobox around Listbox + Popper so you control the fetch lifecycle.
• Standalone filterable lists that aren't form inputs — use Listbox instead

Use specific placeholders

"Buildings" beats "Pick an option". Generic placeholders force the user to read the field label and the placeholder; specific ones (the noun being selected) let the placeholder do double duty.

Multi select

Pass an array as v-model to enable multi-selection.

<Combobox v-model="values" multiple :fuzzy-search="true">
  <ComboboxInput placeholder="Pick several fruits" />
  <ComboboxContent>
    <ComboboxItem v-for="f in fruits" :key="f.value" :value="f.value" :fuzzy-search-data="f.label">
      {{ f.label }}
    </ComboboxItem>
  </ComboboxContent>
</Combobox>

values is Ref<string[]>.

Fuzzy search

The fuzzy-search prop on the root enables typo-tolerant filtering powered by fuse.js. Without it, options aren't filtered at all as the user types.

The fuzzy-search-data prop on each ComboboxItem controls what gets matched against the search term:

• String (single-field) — matches typing against that one string.
• Object (multi-field) — matches against every string property of the object.
• Omit — defaults to matching against the item's value prop.

Multi-field search

To match across multiple fields, pass the whole object.

<Combobox v-model="value" fuzzy-search>
  <ComboboxInput placeholder="Search…" />
  <ComboboxContent>
    <ComboboxItem
      v-for="item in items"
      :key="item.id"
      :value="item.id"
      :fuzzy-search-data="item"
    >
      {{ item.label }}
    </ComboboxItem>
  </ComboboxContent>
</Combobox>

Custom search options

For weighted fields or threshold tuning, pass an options object to fuzzy-search.

<Combobox
  v-model="value"
  :fuzzy-search="{
    keys: [
      { name: 'label', weight: 3 },
      { name: 'name', weight: 1 },
    ],
    threshold: 0.35,
  }"
>
  <ComboboxInput />
  <ComboboxContent>
    <ComboboxItem
      v-for="item in items"
      :key="item.id"
      :value="item.id"
      :fuzzy-search-data="item"
    >
      {{ item.label }}
    </ComboboxItem>
  </ComboboxContent>
</Combobox>

Fuzzy-search options

Option	Type	Default	Description
keys	FuseOptionKey[]	All string properties of fuzzy-search-data	Fields to search, with optional weights.
threshold	number	0.35	Match strictness (0.0 = exact, 1.0 = match anything).
ignoreLocation	boolean	true	When true, matches anywhere in the string instead of biasing toward the start.

Validation states

ComboboxInput accepts the same form-state flags as TextInput.

<Combobox v-model="value">
  <ComboboxInput placeholder="Required" missing />
</Combobox>

Combobox — Props

Combobox extends reka-ui ComboboxRoot — every prop documented there is accepted.

Prop	Type	Default	Description
modelValue	AcceptableValue | AcceptableValue[]	—	Selected value(s). Use v-model. Array enables multi-select.
multiple	boolean	false	Allow selecting multiple values.
disabled	boolean	false	Disable the combobox.
fuzzySearch	boolean | ComboboxFuzzySearchOptions	false	Enable aurora's fuzzy filtering. Pass an options object for fuse.js config.
Form state flags	boolean (each)	—	error, success, warning, missing, disabled, readonly.

ComboboxInput — Props

Prop	Type	Default	Description
placeholder	string	—	Input placeholder.
autoSelectOnFocus	boolean	false	Select existing input text when focused.
Form state flags	boolean (each)	—	Validation/state styling.

ComboboxInput extends reka-ui's ComboboxInput props (minus modelValue, which aurora manages internally).

ComboboxItem — Props

Prop	Type	Default	Description
value	AcceptableValue	required	Item value used by v-model and (when omitted) for fuzzy matching.
fuzzySearchData	string | object	—	Data used for fuzzy matching. Pass a string for single-field search, or an object to search all string properties. Defaults to value when omitted.
disabled	boolean	false	Disable selection.

ComboboxEmpty

Renders its slot content when no items match the current search term.

<ComboboxEmpty>No matches</ComboboxEmpty>