Usage

Typeahead is a single-select search field. The input is a combobox and the menu is a listbox. Use createStaticSource for local data, or implement search for a remote source.

Local search matches the label and optional keywords. Set debounceMs to 0 to filter immediately:

<script setup lang="ts">
import { createStaticSource } from '@astryx-vue/core'
import { Typeahead } from '@astryx-vue/core/Typeahead'
import { ref } from 'vue'

const selected = ref(null)
const source = createStaticSource([
  { id: 'apple', label: 'Apple' },
  { id: 'grape', label: 'Grape' },
], { keywords: item => item.id === 'grape' ? ['raisin'] : [] })
</script>

<template>
  <Typeahead v-model="selected" :search-source="source" label="Fruit" :debounce-ms="0" show-on-focus />
</template>

An async source returns a Promise. useAsyncSource waits until typing pauses, 150 milliseconds by default, then starts the request. A newer search cancels the previous one, and a stale response is dropped. An empty query uses bootstrap when it exists. Loading, no results, and a failed request each get their own row in the menu.

Arrow keys move the highlight, Enter selects it, and Escape closes the menu. While focus is in the input, Home and End move the caret. After a selection, the value collapses to a focusable token. Focusing it again returns to search.

Built-in strings are English. Call provideAstryxLocale('zh-CN') for the Chinese strings.

Best Practices

Guideline	Practice
Do	Set debounceMs to 0 for local data, and keep the default delay for remote requests.
Do	Abort the request when signal is cancelled so an older response cannot replace a newer one.
Don't	Use typeahead for multiple values. Use Multi Selector for a fixed list, and Tokenizer for searchable tags.

Anatomy

Element	Description
Field	Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.
Input surface	Painted control surface containing the editable input or the selected token.
Icon-rendered start icon	Optional leading semantic icon or icon component rendered through Icon.
Caller-rendered start content	Optional arbitrary slot content rendered directly at the start of the input surface.
Selected token	Token that presents the selected item while the control is not in edit mode.
Spinner	Loading indicator shown at the end of the input surface while a search is in flight.
Clear button	Shared clear action that removes the selected item when clearable is set.
Dropdown	Anchored listbox surface containing the current search results.
Empty state	Message shown after a completed search returns no results.
Result row	Stable option wrapper that owns highlight, selection, pointer, and keyboard behavior.
Default item content	The standard label and supporting content rendered inside a result row when the item slot is not provided.
Caller-rendered item content	Caller-owned result content supplied through the item slot, inside the stable result row.
Result group heading	Visible heading for a labeled group of result rows.
Selected result state	Selected styling and trailing check presented on the current result row.

Examples

Limited Results

Country

Typeahead with a capped dropdown showing at most three results.

Search Field

Team member

Search input with icon and suggestions on focus.

With Helper Text

Department

Select the department this request should be routed to

Typeahead with a description below the label.

With Validation

Office

Please select an office location

Typeahead with an error validation message.

Without field chrome

BaseTypeahead has no field label or description. Use it where the page already names the control, such as a command palette, and pass label as the input's accessible name.