AutoComplete
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.