Skip to content
Edit this page

Autocomplete API

The API documentation of the Autocomplete React component. Learn more about the props and the CSS customization points.

Import 

import Autocomplete from '@material-ui/lab/Autocomplete';
// or
import { Autocomplete } from '@material-ui/lab';

You can learn more about the difference by reading this guide.

Props

Name Type Default Description
autoComplete bool false If true, the portion of the selected suggestion that has not been typed by the user, 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.
autoHightlight bool false If true, the first option is automatically highlighted.
autoSelect bool 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.
classes object Override or extend the styles applied to the component. See CSS API below for more details.
clearOnEscape bool false If true, clear all values when the user presses escape and the popup is closed.
debug bool false If true, the popup will ignore the blur event if the input if filled. You can inspect the popup markup with your browser tools. Consider this option when you need to customize the component.
defaultValue any The default input value. Use when the component is not controlled.
disableClearable bool false If true, the input can't be cleared.
disableCloseOnSelect bool false If true, the popup won't close when a value is selected.
disableListWrap bool false If true, the list box in the popup will not wrap focus.
disableOpenOnFocus bool false If true, the popup won't open on input focus.
filterOptions func A filter function that determins the options that are eligible.

Signature:
function(options: any, state: object) => boolean
options: The options to render.
state: The state of the component.
filterSelectedOptions bool false If true, hide the selected options from the list box.
freeSolo bool false If true, the Autocomplete is free solo, meaning that the user input is not bound to provided options.
getOptionDisabled func Used to determine the disabled state for a given option.
getOptionLabel func x => x 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).
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 renderGroup is not provided.

Signature:
function(options: any) => string
options: The option to group.
id string This prop is used to help implement the accessibility logic. If you don't provide this prop. It falls back to a randomly generated id.
includeInputInList bool false If true, the highlight can move to the input.
ListboxComponent elementType 'ul' The component used to render the listbox.
loading bool false If true, the component is in a loading state.
loadingText node 'Loading…' Text to display when in a loading state.
multiple bool false If true, value must be an array and the menu will support multiple selections.
noOptionsText node 'No options' Text to display when there are no options.
onChange func Callback fired when the value changes.

Signature:
function(event: object, value: any) => void
event: The event source of the callback
value: null
onClose func Callback fired when the popup requests to be closed. Use in controlled mode (see open).

Signature:
function(event: object) => void
event: The event source of the callback.
onOpen func Callback fired when the popup requests to be opened. Use in controlled mode (see open).

Signature:
function(event: object) => void
event: The event source of the callback.
open bool Control the popup` open state.
options array [] Array of options.
PaperComponent elementType Paper The component used to render the body of the popup.
PopupComponent elementType Popper The component used to render the popup.
renderGroup func Render the group.

Signature:
function(option: any) => ReactNode
option: The group to render.
renderInput * func Render the input.

Signature:
function(params: object) => ReactNode
params: null
renderOption func Render the option, use getOptionLabel by default.

Signature:
function(option: any, state: object) => ReactNode
option: The option to render.
state: The state of the component.
renderTags func Render the selected value.

Signature:
function(value: any) => ReactNode
value: The value provided to the component.
value any The input value.

The ref is forwarded to the root element.

Any other props supplied will be provided to the root element (native element).

CSS

  • Style sheet name: MuiAutocomplete.
  • Style sheet details:
Rule name Global class Description
root .MuiAutocomplete-root Styles applied to the root element.
focused .Mui-focused Pseudo-class applied to the root element if focused.
tag .MuiAutocomplete-tag Styles applied to the tag elements, e.g. the chips.
inputRoot .MuiAutocomplete-inputRoot Styles applied to the Input element.
input .MuiAutocomplete-input Styles applied to the input element.
inputFocused .MuiAutocomplete-inputFocused Styles applied to the input element if tag focused.
clearIndicator .MuiAutocomplete-clearIndicator Styles applied to the clear indictator.
clearIndicatorDirty .MuiAutocomplete-clearIndicatorDirty Styles applied to the clear indictator if the input is dirty.
popupIndicator .MuiAutocomplete-popupIndicator Styles applied to the popup indictator.
popupIndicatorOpen .MuiAutocomplete-popupIndicatorOpen Styles applied to the popup indictator if the popup is open.
popup .MuiAutocomplete-popup Styles applied to the popup element.
paper .MuiAutocomplete-paper Styles applied to the Paper component.
listbox .MuiAutocomplete-listbox Styles applied to the listbox component.
loading .MuiAutocomplete-loading Styles applied to the loading wrapper.
noOptions .MuiAutocomplete-noOptions Styles applied to the no option wrapper.
option .MuiAutocomplete-option Styles applied to the option elements.
groupLabel .MuiAutocomplete-groupLabel Styles applied to the group's label elements.
groupUl .MuiAutocomplete-groupUl Styles applied to the group's ul elements.

You can override the style of the component thanks to one of these customization points:

If that's not sufficient, you can check the implementation of the component for more detail.

Demos