Typeahead Props

Name	Type	Default	Description
modelValue	T | null	null	Selected item. An item has at least id and label.
searchSource	SearchSource<T>	Required	Static or async source. An empty query prefers bootstrap.
label	string	Required	Field label. Always available to assistive technology.
description	string	—	Helper text under the label.
labelTooltip	string	—	Tooltip text on an info icon next to the label.
isLabelHidden	boolean	false	Hides the label visually while keeping it accessible. labelHidden is the older name; either one hides it.
containerClass / controlClass	class	—	Field shell and input box. A root class lands on the box, not the native input. An item action turns the menu into two columns and does not select the item.
startIcon	Component	—	Icon at the start of the input. An icon slot replaces it.
placeholder	string	Search… / 搜索…	Placeholder. English unless a locale is provided.
debounceMs	number	150	Wait after typing before searching. Use 0 for local data.
minQueryLength	number	1	Shortest query that gets searched, counted in visible characters. Below it nothing is searched and the menu stays closed, so a query nobody searched never reports "no results". An empty query is not "too short": it still bootstraps.
hasEntriesOnFocus	boolean	false	Show bootstrap results on focus before the user types.
showOnFocus	boolean	false	Legacy name for hasEntriesOnFocus. Either one turns it on.
hasAutoFocus	boolean	false	Focus the input on mount.
maxMenuItems	number	10	Maximum rows in the menu.
hasClear	boolean	true	Show a clear button that deselects the current value.
clearable	boolean	true	Legacy name for hasClear. Turning either one off removes the button.
emptySearchText	string | null	'No results found' / '未找到结果'	Text shown when the query matched nothing. null means "not given" and falls through to the default; an empty string renders nothing. For rich content use the empty slot.
emptyText	string | null	—	Legacy name for emptySearchText.
disabled	boolean	false	Disable the field.
disabledMessage	string	—	Explains why the field is disabled. With disabled, the control stays focusable through aria-disabled and readonly instead of the native disabled, and the message shows as a tooltip on hover or keyboard focus.
disabledReason	string	—	Legacy name for disabledMessage.
status	'default' | 'success' | 'warning' | 'error'	'default'	Status style.
statusMessage	string	—	Status text under the field.
size	'sm' | 'md' | 'lg'	'md'	Input and token size.
required	boolean	false	Marks the field as required.
optional	boolean	false	Shows an optional indicator on the label.
name	string	—	Form field name. Submits the selected id.
width	number | string	—	Width of the whole field (number = pixels, string used as-is).

Typeahead Emits

Name	Parameters	Description
update:modelValue	value: T | null	Emitted when the selection is set or cleared.
change	value: T | null	Emitted when the selection is set or cleared.
changeQuery	query: string	Emitted when the query text changes.
search	query: string	Legacy name for changeQuery. Both fire.
openChange	isOpen: boolean	Emitted when the menu opens or closes.

Typeahead Slots

Name	Parameters	Description
icon	—	Icon at the start of the input.
item	{ item, isActive, isSelected }	Custom menu row. Replaces the default TypeaheadItem.
empty	—	Custom empty state.

createStaticSource

Name	Type	Description
items	T[]	Local items.
keywords	(item: T) => string[]	Extra words included in the substring match.

Grouping results

Put a group name on item.auxiliaryData.group. Rows that share a name are rendered as one role="group" block with a visible heading, in the order the groups first appear. Rows without a group stay at their own position.

const items = [
  { id: 'apple', label: 'Apple', auxiliaryData: { group: 'Fruit' } },
  { id: 'carrot', label: 'Carrot', auxiliaryData: { group: 'Vegetable' } },
]

BaseTypeahead

No field label, description, or validation message. Use it where the surrounding surface already has a title, such as a command palette. label here is the input's accessible name; omit it when an outside <label for> already names the input. The default menu row is TypeaheadItem, and the item slot replaces it.

Name	Type	Default	Description
modelValue	T | null	null	Selected item.
searchSource	SearchSource<T>	Required	Static or async source.
label	string	—	Accessible name of the input.
inputId	string	Generated	Id of the input, so an outside label can point at it.
describedBy	string	—	Ids of the description and status the caller already computed.
ariaDescribedBy	string	—	Input-specific alias for aria-describedby. Takes precedence over the native attribute.
ariaLabelledBy	string	—	Input-specific alias for aria-labelledby. Takes precedence over the native attribute.
anchorRef	HTMLElement | null	—	Element the dropdown hangs from and measures itself against. Defaults to the input's own wrapper.
inputTabIndex	number	—	Tab order of the input. Defaults to -1 while the selected token covers the input, so the invisible input is not a tab stop.
isFocusableDisabled	boolean	false	Keep a disabled input focusable through aria-disabled and readonly so a caller-owned disabled reason stays discoverable. Text entry stays blocked.
hasAutoFocus	boolean	false	Focus the input on mount.
hasEntriesOnFocus	boolean	false	Show bootstrap results on focus before the user types.
showOnFocus	boolean	false	Legacy name for hasEntriesOnFocus. Either one turns it on.
minQueryLength	number	1	Shortest query that gets searched, counted in visible characters. Below it nothing is searched and the menu stays closed.
menuWidth	number	—	Requested dropdown width in pixels. Never narrower than the anchor, and clamped to the viewport.
maxMenuItems	number	10	Maximum rows in the menu.
emptySearchText	string | null	'No results found' / '未找到结果'	Text shown when the query matched nothing. null falls through to the default; an empty string renders nothing.
emptyText	string | null	—	Legacy name for emptySearchText.
placeholder	string	Search…	Input placeholder.
disabled	boolean	false	Disable the input.
disabledReason	string	—	Why the input is disabled. Shown as a tooltip and announced as the description while the input stays focusable.
status	'default' | 'success' | 'warning' | 'error'	'default'	Border color of the control.
size	'sm' | 'md' | 'lg'	'md'	Input and token size.
clearable	boolean	true	Show a clear button.
debounceMs	number	150	Wait after typing before searching. Use 0 for local data.
required	boolean	false	Marks the input as required.
name	string	—	Form field name. Submits the selected id.

Name	Parameters	Description
update:modelValue	value: T | null	Emitted when the selection is set or cleared.
change	value: T | null	Emitted when the selection is set or cleared.
changeQuery	query: string	Emitted when the query text changes.
search	query: string	Legacy name for changeQuery. Both fire.
openChange	isOpen: boolean	Emitted when the menu opens or closes.

Native attributes and listeners that are not listed above land on the input element, so @keydown, @focus, @blur and aria-* work as they would on a plain <input>. A keydown listener runs before the internal keyboard navigation; call event.preventDefault() to skip it.

TypeaheadItem

Name	Type	Default	Description
item	SearchableItem	Required	The search result this row shows.
description	string	—	Overrides the item's own description.
group	string	—	Accepted for API parity; the row itself draws no heading. Grouping is done by the menu from item.auxiliaryData.group.
isDisabled	boolean	false	Paints the row as unavailable.
icon (slot)	—	—	Icon or avatar shown before the label.