Autocomplete API
API reference docs for the React Autocomplete component. Learn about the props, CSS, and other APIs of this exported module.
Demos
Import
import Autocomplete from '@mui/material/Autocomplete';
// or
import { Autocomplete } from '@mui/material';
Learn about the difference by reading this guide on minimizing bundle size.
Props of the native component are also available.
Name | Type | Default | Description |
---|---|---|---|
options* | array | - | Array of options. |
renderInput* | func | - | Render the input. Signature: function(params: object) => ReactNode |
autoComplete | bool | false | If |
autoHighlight | bool | false | If |
autoSelect | bool | false | If |
blurOnSelect | 'mouse' | 'touch' | bool | false | Control if the input should be blurred when an option is selected:
|
ChipProps | object | - | Props applied to the |
classes | object | - | Override or extend the styles applied to the component. See CSS classes API below for more details. |
clearIcon | node | <ClearIcon fontSize="small" /> | The icon to display in place of the default clear icon. |
clearOnBlur | bool | !props.freeSolo | If |
clearOnEscape | bool | false | If |
clearText | string | 'Clear' | Override the default text for the clear icon button. |
closeText | string | 'Close' | Override the default text for the close popup icon button. |
componentsProps | { clearIndicator?: object, paper?: object, popper?: object, popupIndicator?: object } | - | The props used for each slot inside. |
defaultValue | any | props.multiple ? [] : null | The default value. Use when the component is not controlled. |
disableClearable | bool | false | If |
disableCloseOnSelect | bool | false | If |
disabled | bool | false | If |
disabledItemsFocusable | bool | false | If |
disableListWrap | bool | false | If |
disablePortal | bool | false | If |
filterOptions | func | createFilterOptions() | A function that determines the filtered options to be rendered on search. Signature: function(options: Array
|
filterSelectedOptions | bool | false | If |
forcePopupIcon | 'auto' | bool | 'auto' | Force the visibility display of the popup icon. |
freeSolo | bool | false | If |
fullWidth | bool | false | If |
getLimitTagsText | func | (more) => `+${more}` | The label to display when the tags are truncated ( Signature: function(more: number) => ReactNode
|
getOptionDisabled | func | - | Used to determine the disabled state for a given option. Signature: function(option: Value) => boolean
|
getOptionKey | func | - | 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). Signature: function(option: Value) => string | number
|
getOptionLabel | func | (option) => option.label ?? option | Used to determine the string value for a given option. It's used to fill the input (and the list box options if Signature: function(option: Value) => string |
groupBy | func | - | If provided, the options will be grouped under the returned string. The groupBy value is also used as the text for group headings when Signature: function(options: Value) => string
|
handleHomeEndKeys | bool | !props.freeSolo | If |
id | string | - | 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. |
includeInputInList | bool | false | If |
inputValue | string | - | The input value. |
isOptionEqualToValue | func | - | 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. Signature: function(option: Value, value: Value) => boolean
|
limitTags | integer | -1 | The maximum number of tags that will be visible when not focused. Set |
ListboxComponent | elementType | 'ul' | The component used to render the listbox. |
ListboxProps | object | - | Props applied to the Listbox element. |
loading | bool | false | If |
loadingText | node | 'Loading…' | Text to display when in a loading state. |
multiple | bool | false | If |
noOptionsText | node | 'No options' | Text to display when there are no options. |
onChange | func | - | Callback fired when the value changes. Signature: function(event: React.SyntheticEvent, value: Value | Array
|
onClose | func | - | Callback fired when the popup requests to be closed. Use in controlled mode (see open). Signature: function(event: React.SyntheticEvent, reason: string) => void
|
onHighlightChange | func | - | Callback fired when the highlight option changes. Signature: function(event: React.SyntheticEvent, option: Value, reason: string) => void
|
onInputChange | func | - | Callback fired when the input value changes. Signature: function(event: React.SyntheticEvent, value: string, reason: string) => void
|
onOpen | func | - | Callback fired when the popup requests to be opened. Use in controlled mode (see open). Signature: function(event: React.SyntheticEvent) => void
|
open | bool | - | If |
openOnFocus | bool | false | If |
openText | string | 'Open' | Override the default text for the open popup icon button. |
PaperComponent | elementType | Paper | The component used to render the body of the popup. |
PopperComponent | elementType | Popper | The component used to position the popup. |
popupIcon | node | <ArrowDropDownIcon /> | The icon to display in place of the default popup icon. |
readOnly | bool | false | If |
renderGroup | func | - | Render the group. Signature: function(params: AutocompleteRenderGroupParams) => ReactNode
|
renderOption | func | - | Render the option, use Signature: function(props: object, option: Value, state: object, ownerState: object) => ReactNode
|
renderTags | func | - | Render the selected value. Signature: function(value: Array
|
selectOnFocus | bool | !props.freeSolo | If |
size | 'small' | 'medium' | string | 'medium' | The size of the component. |
slotProps | { chip?: func | object, clearIndicator?: func | object, listbox?: func | object, paper?: func | object, popper?: func | object, popupIndicator?: func | object } | {} | The props used for each slot inside. |
slots | { listbox?: elementType, paper?: elementType, popper?: elementType } | {} | The components used for each slot inside. |
sx | Array<func | object | bool> | func | object | - | The system prop that allows defining system overrides as well as additional CSS styles. See the `sx` page for more details. |
value | any | - | The value of the autocomplete. |
Theme default props
You can use MuiAutocomplete
to change the default props of this component with the theme.
Slot name | Class name | Default component | Description |
---|---|---|---|
listbox | .MuiAutocomplete-listbox | 'ul' | The component used to render the listbox. |
paper | .MuiAutocomplete-paper | Paper | The component used to render the body of the popup. |
popper | .MuiAutocomplete-popper | Popper | The component used to position the popup. |
These class names are useful for styling with CSS. They are applied to the component's slots when specific states are triggered.
Class name | Rule name | Description |
---|---|---|
.Mui-expanded | State class applied to the root element if the listbox is displayed. | |
.Mui-focused | State class applied to the root element if focused. | |
.Mui-focusVisible | Styles applied to the option elements if they are keyboard focused. | |
.MuiAutocomplete-clearIndicator | clearIndicator | Styles applied to the clear indicator. |
.MuiAutocomplete-endAdornment | endAdornment | Styles applied to the endAdornment element. |
.MuiAutocomplete-fullWidth | fullWidth | Styles applied to the root element if fullWidth={true} . |
.MuiAutocomplete-groupLabel | groupLabel | Styles applied to the group's label elements. |
.MuiAutocomplete-groupUl | groupUl | Styles applied to the group's ul elements. |
.MuiAutocomplete-hasClearIcon | hasClearIcon | Styles applied when the clear icon is rendered. |
.MuiAutocomplete-hasPopupIcon | hasPopupIcon | Styles applied when the popup icon is rendered. |
.MuiAutocomplete-input | input | Styles applied to the input element. |
.MuiAutocomplete-inputFocused | inputFocused | Styles applied to the input element if the input is focused. |
.MuiAutocomplete-inputRoot | inputRoot | Styles applied to the Input element. |
.MuiAutocomplete-loading | loading | Styles applied to the loading wrapper. |
.MuiAutocomplete-noOptions | noOptions | Styles applied to the no option wrapper. |
.MuiAutocomplete-option | option | Styles applied to the option elements. |
.MuiAutocomplete-popperDisablePortal | popperDisablePortal | Styles applied to the popper element if disablePortal={true} . |
.MuiAutocomplete-popupIndicator | popupIndicator | Styles applied to the popup indicator. |
.MuiAutocomplete-popupIndicatorOpen | popupIndicatorOpen | Styles applied to the popup indicator if the popup is open. |
.MuiAutocomplete-root | root | Styles applied to the root element. |
.MuiAutocomplete-tag | tag | Styles applied to the tag elements, for example the chips. |
.MuiAutocomplete-tagSizeMedium | tagSizeMedium | Styles applied to the tag elements, for example the chips if size="medium" . |
.MuiAutocomplete-tagSizeSmall | tagSizeSmall | Styles applied to the tag elements, for example the chips if size="small" . |
You can override the style of the component using one of these customization options:
- With a global class name.
- With a rule name as part of the component's
styleOverrides
property in a custom theme.