On this page

Input with autocomplete (combobox)

InputAutocomplete is a text field with a suggestion list. Its value remains a free-form string: text that is not in the list stays in the field, and selecting a suggestion fills the field. Use Select with filter when the value must be one of the options.

InputAutocomplete uses an Input for the field and a Menu for suggestions. onValueChange reports field text. onSelect runs only after someone chooses a suggestion. Use value to control it, or defaultValue for uncontrolled use.

Playground

Free text is the point

value: — — type something not in the list; it stays.

The value is always the text in the field. That’s what separates this from a Select: a Select constrains the value to one of its options, so a Select with filter already covers “search a fixed list”. InputAutocomplete is for when the list only suggests and the user may commit something you didn’t list.

The keyboard follows that intent. No suggestion is highlighted as you type, so Enter commits the typed text and closes the list. ↓ highlights the first suggestion (then ↑/↓ move through them), and Enter on a highlighted row picks it. Esc or an outside click closes the list; clicking the field to place the caret keeps it open.

The focused field is associated directly with the suggestion popup and its active option through ARIA element reflection. These relationships do not require generated popup or option IDs, so separate application roots cannot collide. Explicit ARIA relationships authored on a raw Anta Input take precedence.

Filtering

filter decides how suggestions match the text:

true (default): built-in case-insensitive substring match on each option’s value / label / hint.
a function (option, query) => boolean: a custom matcher, called for each option.
false: show suggestions as-is, doing no local filtering. Use this when you fetch or filter results yourself (async / remote) and feed the current set through suggestions.

Suggestions are bare strings or SelectOptions, the same option shape Select uses: value, label, hint, icon, tone, disabled.

Component props

Prop	Type	Default	Description
suggestions	stringSelectOption[]	—	The suggestions: bare strings or `SelectOption`s (`value` / `label` / `hint` / `icon` / `tone` / `disabled`). A flat list; picking one fills the field.
value?	string	—	Controlled value: the field's text, a free string not constrained to a suggestion. Leave undefined for uncontrolled.
defaultValue?	string	—	Initial value for uncontrolled use.
onValueChange?	(value) => void	—	Fires as the text changes (typing, picking a suggestion, or clearing) with the new field text.
onSelect?	(option) => void	—	Fires only when a suggestion is chosen, with that option.
filter?	boolean(option, query) => boolean	`true`	How suggestions match the text. `true` uses the built-in case-insensitive substring match on `value` / `label` / `hint`; a function `(option, query) => boolean` uses a custom matcher; `false` shows `suggestions` unchanged for application-provided async or remote filtering.
placeholder?	string	—	Placeholder text.
size?	`smallmediumlarge`	`medium`	Field size.
status?	`neutralbrandinfosuccesswarningcritical`	—	Validation status.
statusIcon?	string`false`IconShape	—	Status icon override, or `false` to drop it.
tone?	string	—	Custom accent color — a named tone or any CSS color.
clearable?	boolean	—	Show a clear button while the field has text.
name?	string	—	Form field name.
disabled?	boolean	—	Disable the field.
label?	ReactNode	—	Field label.
hint?	ReactNode	—	Hint under the field.
leading?	ReactNode	—	Leading adornment inside the field.
trailing?	ReactNode	—	Trailing adornment inside the field.

Inherited props (className, id, slot, style, tabIndex, title)

Prop	Type	Default	Description
className?	string	—	CSS class on the component's root element (merged with the component's own classes). Use it directly for layout and positioning — grid/flex placement, margins, alignment — rather than wrapping the component in a `<div>`/`<span>`.
id?	string	—	HTML `id` attribute.
slot?	string	—	Assigns the element to a named `<slot>` of a parent web component (e.g. `slot="header"` inside a `<Card>`, `slot="footer"` inside a `<Dialog>`).
style?	CSSProperties	—	Inline styles on the component's root element. Set layout/positioning here (or via `className`) directly on the component instead of adding a wrapper.
tabIndex?	number	—	Tab order. Set to `-1` to skip the element when tabbing.
title?	string	—	HTML `title` attribute — native browser tooltip on hover.

Plus every standard DOM event handler (onClick, onFocus, onKeyDown, …) and any data-* or aria-* attribute — forwarded as-is to the underlying <a-*> element.

Web Component

InputAutocomplete combines an input with a Menu. Reproducing its filtering, selection, focus, and popup coordination without the React or Preact wrapper is a substantial amount of code.

Native HTML input with autocomplete

For browser-native suggestions, pair a native input with a <datalist>. It keeps free-form entry and lets the browser filter and fill matching options, while data-anta supplies the field appearance.

The browser renders the suggestions popup. Use InputAutocomplete for custom option content, popup styling, or consistent behavior across browsers.

<input 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>

Styling

The field is styled through Input’s props (size, status, tone, round, leading / trailing) and its ::parts; set its width with style / className (forwarded to the field). The suggestion popover takes Menu’s ::part(menu).

// Give the field a width; tint it with a custom tone.
<InputAutocomplete tone="info" style={{ width: '260px' }} suggestions={frameworks} />