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.

The options list uses bridge-soft-scrollbar. See Scroll utilities.

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.

Multiple

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

Async data

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

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.

Match field width

Set customProps.listbox.matchWidth so the menu panel matches the field. Only applies when the overlay resolves to menu.

<Autocomplete
  label="Country"
  :options="countries"
  :custom-props="{
    listbox: { matchWidth: true },
  }"
/>

<Autocomplete
  label="Country"
  options={countries}
  customProps={{
    listbox: { matchWidth: true },
  }}
/>

To apply this to every Select / Autocomplete menu, set components.Listbox.defaultProps.matchWidth — see Default props.

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
default-value	SelectModel	—	Initial value for uncontrolled usage (without v-model).
v-model	SelectModel	—	Two-way binding for the selected value (single or multiple).

Prop	Type	Default	Description
onChange	(value: SelectModel) => void	—	Called when the selection changes.
value	SelectModel	—	Selected value (single or multiple). Use with onChange for controlled state.

Autocomplete-specific

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

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).
@change	value: SelectModel	Emitted when the value changes (alternative to v-model).
@clear	—	Emitted when the value is cleared.
@close	—	Emitted when the menu closes.
@deselect	option: SelectOption	Emitted when an option is deselected (multiple mode).
@open	—	Emitted when the menu opens.
@search	query: string	Emitted when the search query changes.
@select	option: SelectOption	Emitted when an option is selected.

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.
onDeselect	option: SelectOption	Called when an option is deselected (multiple mode).
onOpen	—	Called when the menu opens.
onSearch	query: string	Called when the search query changes.
onSelect	option: SelectOption	Called when an option is selected.

Slots

Slot	Description
afterOptions	Content below the option list.
beforeOptions	Content above the option list.
chip	Custom chip content in multiple mode ({ option }).
empty	Custom empty-state content.
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).
option	Custom option item content ({ option, selected }).

Inherited from FormField

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