Bridge UI

Autocomplete

Combobox with search, free-solo input, multiple selection, and async data.

Introduction

Autocomplete is a combobox built on the same foundation as Select—FormField chrome, Menu listbox, chips, async data, and composed list children.

Use Autocomplete when users should type to filter and optionally commit custom values. Use Select when the value must come from a fixed list and search is optional.

Prop Select default Autocomplete default
searchable false true
freeSolo — true

Import

import { Autocomplete } from "@bridge-ui/vue/Components/Autocomplete";
import { Autocomplete } from "@bridge-ui/react/Components/Autocomplete";

Basic usage

Pass an options array of objects with label and value keys. Search is enabled by default. For an initial value without binding, use defaultValue in React or default-value in Vue.

Free solo

Enabled by default. Type a value that is not in options and commit with Enter, Tab, or by closing the menu. Set freeSolo={false} (React) or :free-solo="false" (Vue) to require picking from the list.

freeSolo is on by default — commit custom text with Enter, Tab, or by closing the menu.

freeSolo is on by default — commit custom text with Enter, Tab, or by closing the menu.

Multiple

Enable multiple to allow selecting more than one option. Selected values render as chips.

React
React

Async data

Pass asyncData with search and resolve callbacks for remote or debounced option lists. Implies searchable.

Client-side asyncData with search and resolve callbacks.

Client-side asyncData with search and resolve callbacks.

Overlay

Use the overlay prop to choose the picker shell: auto (default), menu, modal, or drawer. auto uses menu on desktop and a bottom drawer on mobile. When unset, showFooter defaults to true for modal / drawer overlays (false for menu). Apply commits and closes; Cancel discards and closes.

Validation

Set error and errorMessage to show invalid styling and an error message below the field.

Please select a valid country.

Please select a valid country.

Select, Menu, List

Accessibility

Autocomplete follows the FormField accessibility pattern and WAI-ARIA combobox behavior for the searchable trigger.

  • Label, helper text, and error message are linked via controlId and aria-describedby.
  • When error is true, the trigger receives aria-invalid="true".

Anatomy

FormField (root)
├── Header — label, optional corner text, required indicator
├── Container — variant shell
│   └── Trigger — searchable input / chips showing the current selection
├── Options panel — filterable listbox (supports loading and free-solo commit)
└── Footer — description or error message

API

Prop Type Default Description
v-model SelectModel — Two-way binding for the selected value (single or multiple).
default-value SelectModel — Initial value for uncontrolled usage (without v-model).
Prop Type Default Description
value SelectModel — Selected value (single or multiple). Use with onChange for controlled state.
onChange (value: SelectModel) => void — Called when the selection changes.

Autocomplete-specific

Prop Type Default Description
options ListboxOptionsInput — Options to display. May include section groups ({ title, options, sticky? }) mixed with flat options.
children ReactNode — Composed dropdown content (ListSection / ListItem with value). Replaces mapped options.
placeholder string — Placeholder when no value is selected.
overlay FieldOverlayMode "auto" Overlay shell: menu, modal, drawer, or auto.
multiple boolean false Whether multiple values can be selected.
searchable boolean true Whether options can be filtered via the trigger input.
freeSolo boolean true Allows committing typed text that is not in options (Enter, Tab, or closing the menu).
clearable boolean true Whether the value can be cleared.
showFooter boolean false (true for modal/drawer when unset) Shows Cancel / Apply on the nested listbox. Selection stays draft until Apply.
asyncData SelectAsyncData — Remote data source. Implies searchable.
loading boolean — External or async loading state (OR’d with async in-flight).
loadingMessage string "Loading..." Message shown in the dropdown while loading.
defaultValue SelectModel | null — Initial value when uncontrolled.
optionLabel string "label" Key used to read the label from option objects.
optionValue string "value" Key used to read the value from option objects.
optionDescription string "description" Key used to read the description from option objects.
minItemsForSearch number 11 Minimum option count before search UI is enabled.
emptyMessage string "No options" Message when the filtered list is empty.
hideEmptyMessage boolean false Hides the empty-state message.
flipOptions boolean false Inverts the visual order of options.
maxHeight string "max-h-60" Tailwind max-height class for the dropdown options area.
disableMaxHeight boolean false When true, the dropdown options list is not height-limited.

Events

Event Payload Description
@apply — Emitted when Apply is pressed on the listbox footer (showFooter).
@cancel — Emitted when Cancel is pressed on the listbox footer (showFooter).
@clear — Emitted when the value is cleared.
@close — Emitted when the menu closes.
@open — Emitted when the menu opens.
@search query: string Emitted when the search query changes.
@select option: SelectOption Emitted when an option is selected.
@deselect option: SelectOption Emitted when an option is deselected (multiple mode).
@change value: SelectModel Emitted when the value changes (alternative to v-model).
Prop Payload Description
onApply — Called when Apply is pressed on the listbox footer (showFooter).
onCancel — Called when Cancel is pressed on the listbox footer (showFooter).
onClear — Called when the value is cleared.
onClose — Called when the menu closes.
onOpen — Called when the menu opens.
onSearch query: string Called when the search query changes.
onSelect option: SelectOption Called when an option is selected.
onDeselect option: SelectOption Called when an option is deselected (multiple mode).

Slots

Slot Description
chip Custom chip content in multiple mode ({ option }).
option Custom option item content ({ option, selected }).
footer Custom footer. Replaces Cancel / Apply. Call apply() to commit and close, or cancel() to discard.
loading Custom loading content in the dropdown (progress bar still renders above).
empty Custom empty-state content.
beforeOptions Content above the option list.
afterOptions Content below the option list.

Inherited from FormField

Prop Type Default Description
label string — Primary label text above the control.
description string — Helper text below the control (hidden when invalid).
corner string — Secondary label text at the inline end of the header row.
required boolean false Shows a red asterisk on the label.
disabled boolean false Whether the control is disabled.
readonly boolean false Whether the control is read-only.
error boolean false Applies invalid styling and hides description.
errorMessage string — Error message below the control.
showErrorIcon boolean true Shows an error icon when invalid.
hideErrorMessage boolean false Does not reserve space for error messages.
variant FormFieldVariant "outline" Visual variant of the field shell.
color FormFieldColor "primary" Color applied to the field control.
size FormFieldSize "md" Typography and control sizing.
rounded FormFieldRounded "md" Border radius of the field control and the listbox dropdown panel.
start string — Inline-start text inside the field (prefix).
end string — Inline-end text inside the field (suffix).
startIcon IconSource — Icon at the inline start.
endIcon IconSource — Icon at the inline end.
errorIcon IconSource "alert" Icon shown when invalid and showErrorIcon is enabled.
controlId string — Associates labels and helper text with the control. Auto-generated when omitted.
classes FormFieldClasses — Class overrides per part.
customProps SelectCustomProps — FormField parts plus nested listbox, chip, clearIcon, and overlay shells (menu, modal, drawer). label accepts Label props (without children).
slots FormFieldSlots — React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end.