Autocomplete
An autocomplete component is a text input enhanced by a panel of suggested options.
useAutocomplete API
Import
import { useAutocomplete } from '@mui/base/useAutocomplete';
// or
import { useAutocomplete } from '@mui/base';If true, the portion of the selected suggestion that the user hasn't typed, known as the completion string, appears inline after the input cursor in the textbox. The inline completion string is visually highlighted and has a selected state.
Type:boolean
Default:false
If true, the selected option becomes the value of the input when the Autocomplete loses focus unless the user chooses a different option or changes the character string in the input.
When using the freeSolo mode, the typed value will be the input value if the Autocomplete loses focus without highlighting an option.
Type:boolean
Default:false
Control if the input should be blurred when an option is selected:
falsethe input is not blurred.truethe input is always blurred.touchthe input is blurred after a touch event.mousethe input is blurred after a mouse event.
Type:'touch' | 'mouse' | true | false
Default:false
If true, the input's text is cleared on blur if no value is selected.
Set it to true if you want to help the user enter a new value. Set it to false if you want to help the user resume their search.
Type:boolean
Default:!props.freeSolo
If true, clear all values when the user presses escape and the popup is closed.
Type:boolean
Default:false
The default value. Use when the component is not controlled.
Type:AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>
Default:props.multiple ? [] : null
If true, the popup won't close when a value is selected.
Type:boolean
Default:false
A function that determines the filtered options to be rendered on search.
Type:(options: Value[], state: FilterOptionsState<Value>) => Value[]
Default:createFilterOptions()
If true, the Autocomplete is free solo, meaning that the user input is not bound to provided options.
Type:FreeSolo
Default:false
Used to determine the disabled state for a given option.
Type:(option: Value) => boolean
Used to determine the key for a given option. This can be useful when the labels of options are not unique (since labels are used as keys by default).
Type:(option: Value | AutocompleteFreeSoloValueMapping<FreeSolo>) => string | number
Used to determine the string value for a given option. It's used to fill the input (and the list box options if renderOption is not provided).
If used in free solo mode, it must accept both the type of the options and a string.
Type:(option: Value | AutocompleteFreeSoloValueMapping<FreeSolo>) => string
Default:(option) => option.label ?? option
If provided, the options will be grouped under the returned string. The groupBy value is also used as the text for group headings when renderGroup is not provided.
Type:(option: Value) => string
If true, the component handles the "Home" and "End" keys when the popup is open. It should move focus to the first option and last option, respectively.
Type:boolean
Default:!props.freeSolo
This prop is used to help implement the accessibility logic. If you don't provide an id it will fall back to a randomly generated one.
Type:string
Used to determine if the option represents the given value. Uses strict equality by default. ⚠️ Both arguments need to be handled, an option can only match with one value.
Type:(option: Value, value: Value) => boolean
If true, value must be an array and the menu will support multiple selections.
Type:Multiple
Default:false
Callback fired when the value changes.
Type:(event: React.SyntheticEvent, value: AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>, reason: AutocompleteChangeReason, details?: AutocompleteChangeDetails<Value>) => void
Callback fired when the popup requests to be closed. Use in controlled mode (see open).
Type:(event: React.SyntheticEvent, reason: AutocompleteCloseReason) => void
Callback fired when the highlight option changes.
Type:(event: React.SyntheticEvent, option: Value | null, reason: AutocompleteHighlightChangeReason) => void
Callback fired when the input value changes.
Type:(event: React.SyntheticEvent, value: string, reason: AutocompleteInputChangeReason) => void
Callback fired when the popup requests to be opened. Use in controlled mode (see open).
Type:(event: React.SyntheticEvent) => void
If true, the component becomes readonly. It is also supported for multiple tags where the tag cannot be deleted.
Type:boolean
Default:false
If true, the input's text is selected on focus. It helps the user clear the selected value.
Type:boolean
Default:!props.freeSolo
Resolver for the clear button element's props.
Type:() => React.HTMLAttributes<HTMLButtonElement>
Resolver for the input label element's props.
Type:() => Omit<React.HTMLAttributes<HTMLLabelElement>, 'color'>
Resolver for the input element's props.
Type:() => React.InputHTMLAttributes<HTMLInputElement> & {
ref: React.Ref<HTMLInputElement>
}
Resolver for the listbox component's props.
Type:() => React.HTMLAttributes<HTMLUListElement>
Resolver for the rendered option element's props.
Type:(renderedOption: UseAutocompleteRenderedOption<Value>) => React.HTMLAttributes<HTMLLIElement>
Resolver for the popup icon's props.
Type:() => React.HTMLAttributes<HTMLButtonElement>
Resolver for the root slot's props.
Type:(externalProps?: any) => React.HTMLAttributes<HTMLDivElement>
The options to render. It's either Value[] or AutocompleteGroupedOption<Value>[] if the groupBy prop is provided.
Type:Value[] | Array<AutocompleteGroupedOption<Value>>