Input with autocomplete (combobox) ✦Documentation has not yet been reviewed by a human.

InputAutocomplete offers suggestions while people enter text. Use it for package names, search queries, or other fields where common entries help but people can also enter their own value. Choosing a suggestion fills the field with its value. Use Select when an option’s identity is the value.

Give the field a visible label. If you omit it, provide aria-label or aria-labelledby. A placeholder alone does not name the field.

Free text is the point

The field keeps whatever someone types, including text absent from the list. onValueChange reports that text as it changes. Use onSelect when the application also needs to know that someone chose a suggestion.

const frameworks = ['React', 'Preact', 'Solid', 'Svelte', 'Vue', 'Angular', 'Qwik', 'Lit', 'Astro']
const [value, setValue] = useState('')

<InputAutocomplete
  label="Framework"
  placeholder="Type to search…"
  clearable
  suggestions={frameworks}
  value={value}
  onValueChange={setValue}
/>
<div>Value: <code>{value || '(empty)'}</code></div>

Suggestions

Use strings for a simple list, or option objects to show a readable label, a supporting hint, or an icon. Choosing a row fills the field with its value, so the Anta suggestion here fills in @antadesign/anta. Disabled suggestions remain visible and are skipped during keyboard navigation.

<InputAutocomplete
  label="Package"
  hint="Choose a package name or enter another."
  suggestions={[
    { value: '@antadesign/anta', label: 'Anta', hint: 'UI components', icon: 'cube' },
    { value: '@antadesign/plot', label: 'Plot', hint: 'Canvas charts', icon: 'workflow' },
    { value: '@antadesign/stickers', label: 'Stickers', hint: 'Illustrations', icon: 'asterisk' },
    { value: '@antadesign/archived', label: 'Archived', hint: 'Unavailable', disabled: true },
  ]}
/>

Managing the value

Pass value and update it through onValueChange when another part of your application needs the text. Reset controlled text with ''. For a field that keeps its own text, use defaultValue; a form reset restores that default without opening an unfocused field’s suggestions or moving focus.

const [value, setValue] = useState('React')

<InputAutocomplete label="Framework" suggestions={frameworks}
  value={value} onValueChange={setValue} clearable />
<Button label="Reset text" onClick={() => setValue('')} />

Filtering

The built-in filter matches the value, label, and hint without case sensitivity, and highlights matching label and hint text. Use a function when your application needs a different rule, such as matching word prefixes. It receives the original field text, including whitespace; decide whether to trim it in your matcher.

<InputAutocomplete
  label="Framework prefix"
  suggestions={frameworks}
  filter={(option, query) => option.value.toLowerCase().startsWith(query.trim().toLowerCase())}
/>

Application-provided results

Pass filter={false} when your application already selects or ranks the suggestions. This preserves their order and skips local highlighting. The example supplies matching projects in reverse order; fetched results use the same pattern.

const projects = ['Billing service', 'Billing dashboard', 'Build tools', 'Customer portal']
const [value, setValue] = useState('')
const results = projects.filter(name => name.toLowerCase().includes(value.toLowerCase())).reverse()

<InputAutocomplete
  label="Project"
  hint="Results use the application's order. You can also enter a new project."
  suggestions={results}
  filter={false}
  value={value}
  onValueChange={setValue}
/>

Replace suggestions as results arrive. New results update an open list; they do not reopen it after Escape or focus loss. Your application owns loading, request cancellation, and discarding responses for older queries.

Keyboard interaction

Typing leaves every suggestion inactive, so Enter keeps the typed text and closes the list. Arrow Down highlights the first enabled suggestion; Arrow Up and Arrow Down move through the list. Enter on an active suggestion fills the field. Editing again clears that active suggestion. Input-method composition keeps its own candidate navigation and confirmation keys.

Escape closes the list and keeps focus in the field. Tab closes it and moves to the next control. Selecting a suggestion or clicking the list’s padding keeps focus in the field. Clicking within an open field leaves the list open while placing the caret. The field exposes combobox semantics, the popup is a listbox, and the active suggestion is associated directly with the focused input.

Events

Use onValueChange for application text state. onInput, onFocus, onBlur, and onKeyDown also receive their field events. An input event reports an edit that already happened; preventDefault() does not reject the text.

A consumer onKeyDown can prevent the wrapper’s plain-Enter dismissal. Menu handles active suggestions and navigation earlier in document capture. Those actions cannot be canceled from the field callback, and Escape is consumed before it reaches the field. See the callback reference for ordering.

<label for="autocomplete-people">Person</label>
<input id="autocomplete-people" data-anta type="text" list="people" placeholder="Search people">
<datalist id="people">
  <option value="Maya Chen">
  <option value="Noah Williams">
  <option value="Olivia Martinez">
  <option value="Liam Johnson">
</datalist>

<InputAutocomplete className="package-field" label="Package" suggestions={packages} tone="info" />

.package-field { width: 260px; }
.package-field::part(field) { border-radius: 12px; }
.package-field + a-menu::part(menu) { border-radius: 12px; }