Skip to main content
The autocomplete is a normal text input enhanced by a panel of suggested options.

Import

import Autocomplete from '@mui/material/Autocomplete';
import TextField from '@mui/material/TextField';

Basic Usage

import * as React from 'react';
import TextField from '@mui/material/TextField';
import Autocomplete from '@mui/material/Autocomplete';

const options = ['Option 1', 'Option 2'];

export default function BasicAutocomplete() {
  const [value, setValue] = React.useState<string | null>(options[0]);
  const [inputValue, setInputValue] = React.useState('');

  return (
    <Autocomplete
      value={value}
      onChange={(event: any, newValue: string | null) => {
        setValue(newValue);
      }}
      inputValue={inputValue}
      onInputChange={(event, newInputValue) => {
        setInputValue(newInputValue);
      }}
      options={options}
      sx={{ width: 300 }}
      renderInput={(params) => <TextField {...params} label="Controllable" />}
    />
  );
}

Props

options
T[]
required
Array of options.
renderInput
(params: object) => ReactNode
required
Render the input. Signature: function(params: object) => ReactNode. params contains props to apply to the input element.
value
T | T[] | null
The value of the autocomplete. The value must have reference equality with the option in order to be selected. You can customize the equality behavior with the isOptionEqualToValue prop.
defaultValue
T | T[]
The default value. Use when the component is not controlled.
inputValue
string
The input value.
multiple
boolean
default:"false"
If true, value must be an array and the menu will support multiple selections.
disableCloseOnSelect
boolean
default:"false"
If true, the popup won’t close when a value is selected.
disabled
boolean
default:"false"
If true, the component is disabled.
disableClearable
boolean
default:"false"
If true, the input can’t be cleared.
freeSolo
boolean
default:"false"
If true, the Autocomplete is free solo, meaning that the user input is not bound to provided options.
autoComplete
boolean
default:"false"
If true, the portion of the selected suggestion that the user hasn’t typed, if there is one, is automatically appended to the textbox.
autoHighlight
boolean
default:"false"
If true, the first option is automatically highlighted.
autoSelect
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.
loading
boolean
default:"false"
If true, the component is in a loading state. This shows the loadingText in place of suggestions (only if there are no suggestions to show, for example options are empty).
loadingText
ReactNode
default:"'Loading…'"
Text to display when in a loading state.
noOptionsText
ReactNode
default:"'No options'"
Text to display when there are no options.
open
boolean
If true, the component is shown.
size
'small' | 'medium'
default:"'medium'"
The size of the component.
getOptionLabel
(option: T) => string
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).
isOptionEqualToValue
(option: T, value: T) => boolean
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.
filterOptions
(options: T[], state: object) => T[]
A filter function that determines the options that are eligible. Signature: function(options: Array<T>, state: object) => Array<T>.
groupBy
(option: T) => string
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.
onChange
(event: React.SyntheticEvent, value: T | T[] | null, reason: string, details?: object) => void
Callback fired when the value changes.
onInputChange
(event: React.SyntheticEvent, value: string, reason: string) => void
Callback fired when the input value changes.
onOpen
(event: React.SyntheticEvent) => void
Callback fired when the popup requests to be opened. Use in controlled mode (see open).
onClose
(event: React.SyntheticEvent, reason: string) => void
Callback fired when the popup requests to be closed. Use in controlled mode (see open).
renderOption
(props: object, option: T, state: object) => ReactNode
Render the option, use getOptionLabel by default. Signature: function(props: object, option: T, state: object) => ReactNode.
renderGroup
(params: object) => ReactNode
Render the group. Signature: function(params: AutocompleteRenderGroupParams) => ReactNode.
renderTags
(value: T[], getTagProps: function) => ReactNode
Render the selected value.
ChipProps
ChipProps
Props applied to the Chip element.
sx
SxProps<Theme>
The system prop that allows defining system overrides as well as additional CSS styles.

API Reference

Build docs developers (and LLMs) love