Autocomplete

The autocomplete is a normal text input enhanced by a panel of suggested options.

The widget is useful for setting the value of a single-line textbox in one of two types of scenarios:

1. The value for the textbox must be chosen from a predefined set of allowed values, e.g., a location field must contain a valid location name: combo box.
2. The textbox may contain any arbitrary value, but it is advantageous to suggest possible values to the user, e.g., a search field may suggest similar or previous searches to save the user time: free solo.

Combo box

The value must be chosen from a predefined set of allowed values.

<Autocomplete
  options={top100Films}
  getOptionLabel={option => option.title}
  style={{ width: 300 }}
  renderInput={params => (
    <TextField {...params} label="Combo box" variant="outlined" fullWidth />
  )}
/>

Playground

Each of the following examples demonstrate one feature of the Autocomplete component.

Country select

Choose one country between 248.

Free solo

Set freeSolo to true so the textbox can contain any arbitrary value.

Grouped

<Autocomplete
  options={options.sort((a, b) => -b.firstLetter.localeCompare(a.firstLetter))}
  groupBy={option => option.firstLetter}
  getOptionLabel={option => option.title}
  style={{ width: 300 }}
  renderInput={params => (
    <TextField {...params} label="With categories" variant="outlined" fullWidth />
  )}
/>

Disabled options

<Autocomplete
  options={timeSlots}
  getOptionDisabled={option => option === timeSlots[0] || option === timeSlots[2]}
  style={{ width: 300 }}
  renderInput={params => (
    <TextField
      {...params}
      label="Disabled options"
      variant="outlined"
      fullWidth
      inputProps={{
        ...params.inputProps,
        autoComplete: 'disabled', // disable autocomplete and autofill
      }}
    />
  )}
/>

useAutocomplete

For advanced customization use cases, we expose a useAutocomplete() hook. It accepts almost the same options as the Autocomplete component minor all the props related to the rendering of JSX. The Autocomplete component uses this hook internally.

import useAutocomplete from '@material-ui/lab/useAutocomplete';

• 📦 4 kB gzipped.

Customized useAutocomplete

WIP: to implement this design.

Head to Customized Autocomplete for a customization example with the Autocomplete component instead of the hook.

Asynchronous requests

Google Maps place

A customized UI for Google Maps Places Autocomplete. For this demo, we need to load the Google Maps JavaScript API.

Multiple values

Also knowned as tags, the user is allowed to enter more than 1 value.

Fixed options

In the event that you need to lock certain tag so that they can't be removed in the interface, you can set the chips disabled.

Checkboxes

Customized Autocomplete

This demo reproduces the GitHub's label picker:

Highlights

The following demo relies on autosuggest-highlight, a small (1 kB) utility for highlighting text in autosuggest and autocomplete components.

Customer filter

The component exposes a factory to create a filter method that can provided to the filerOption prop. You can use it to change the default option filter behavior.

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

It supports the following options:

1. config (Object [optional]):
   • config.ignoreAccents (Boolean [optional]): Defaults to true. Remove diacritics.
   • config.ignoreCase (Boolean [optional]): Defaults to true. Lowercase everything.
   • config.matchFrom ('any' | 'start' [optional]): Defaults to 'any'.
   • config.stringify (Func [optional]): Defaults to JSON.stringify.
   • config.trim (Boolean [optional]): Defaults to false. Remove trailing spaces.

In the following demo, the options need to start with the query prefix:

const filterOptions = createFilterOptions({
  matchFrom: 'start',
  stringify: option => option.title,
});

<Autocomplete filterOptions={filterOptions} />

For richer filtering mechanisms, it's recommended to look at match-sorter. For instance:

import matchSorter from 'match-sorter';

const filterOptions = (options, { inputValue }) =>
  matchSorter(options, inputValue);

<Autocomplete filterOptions={filterOptions} />

Virtualization

Search within 10,000 randomly generated options. The list is virtualized thanks to react-window.

<Autocomplete
  style={{ width: 300 }}
  disableListWrap
  classes={classes}
  ListboxComponent={ListboxComponent}
  options={Array.from(new Array(10000)).map(() => random(Math.ceil(Math.random() * 18)))}
  renderInput={params => (
    <TextField {...params} variant="outlined" label="10,000 options" fullWidth />
  )}
/>

Accessibility

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#combobox)

We encourage the usage of a label for the textbox. The component implements the WAI-ARIA authoring practices.

API

• <Autocomplete />
• <Popper />
• <TextField />