AutoComplete
Use AutoComplete when people type free text and suggestions only help them finish it, such as an email address, a search query or a tag name: whatever they type is a valid value. When the value must be one of a known set of options, use Select; to suggest people or items after an @ inside longer text, use Mention.
AutoComplete is a text field that suggests completions as you type. It doesn’t filter anything itself: you pass the options for the current text, computed locally or fetched. It is an Input driving the option list shared with Select; focus stays in the input the whole time, as in the WAI-ARIA combobox pattern with list autocomplete.
#Demos
#Basic
The menu opens while you type (when there are options) and is as wide as the field. The first suggestion is active, so Enter picks it; ↑ / ↓ move. Picking puts the option’s label in the field. A string option is shorthand for { label, value }.
#Filter and groups
Filter the options yourself; groups work as in Select. getShow decides when the menu may show: here always, so focusing the empty field lists everything. Input props such as prefix pass through.
#Picking as an action
onSelect gets the picked value. With clearAfterSelect the field empties after a pick, which suits “add a label” inputs; append adds the label to the text instead of replacing it, and blurAfterSelect moves focus away.
#Remote suggestions
Fetch the options as the text changes; loading shows Input’s spinner meanwhile.
#Keyboard
With the menu open: ↑ / ↓ move the active suggestion (skipping disabled ones and wrapping), Enter picks it, Escape closes it. Typing reopens it, and so does ↓. Other keys edit the text. While an IME is composing, Enter confirms the composition, not a suggestion.
#Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
options | AutoCompleteMixedOption[] | required | Suggestions for the current text: strings, { label, value, disabled? }, or groups { type: "group", label, key, children }. | Unreleased |
value | string | null | undefined | Controlled value. | Unreleased |
defaultValue | string | null | null | Initial value when uncontrolled. | Unreleased |
onUpdateValue | (value: string | null) => void | undefined | Called on every edit, pick and clear. | Unreleased |
onSelect | (value, option) => void | undefined | Called with the picked option. | Unreleased |
append | boolean | false | Picking appends the label to the text. | Unreleased |
clearAfterSelect | boolean | false | Picking empties the field. | Unreleased |
blurAfterSelect | boolean | false | Picking blurs the field. | Unreleased |
getShow | (value: string) => boolean | text isn’t empty | Whether the menu may show for this text. | Unreleased |
showEmpty | boolean | false | Show the menu with the empty text when there are no options. | Unreleased |
empty | ReactNode | locale “No data” | The empty text. | Unreleased |
renderLabel | (option, selected) => ReactNode | undefined | Custom label in the menu. | Unreleased |
placement | PopoverPlacement | bottom-start | Where the menu opens. | Unreleased |
to / zIndex | Same as Popover. | Unreleased |
It also takes Input’s props except type, autosize, rows and showPasswordOn: size, status, clearable, loading, prefix, suffix, disabled, placeholder, ref (the input), wrapperRef and native attributes.