Skip to content
+

Autocomplete

The autocomplete is a text input enhanced by a panel of suggested options when users start typing.

Introduction

Autocomplete is an enhanced version of text input that shows suggested options as the users type and also let them select an option from the list.


Flags
  • The completion string, appears inline after the input cursor in the textbox. The inline completion string is visually highlighted and has a selected state.
  • The first option is automatically highlighted.
  • 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.
  • The input is always blurred.
  • The input's text is cleared on blur if no value is selected.
  • Clear all values when the user presses escape and the popup is closed.
  • The component is disabled.
  • The input can't be cleared
  • The popup won't close when a value is selected.
  • The list box in the popup will not wrap focus.
  • Hide the selected option from the list box.
  • The user input is not bound to the provided options.
  • The highlight can move to the input.
  • The popup will open on input focus.
  • The popup will be under the DOM hierarchy of the parent component.
  • The component becomes read-only. It is also supported in multiple tags where the tag cannot be deleted.
  • The input's text is selected on focus. It helps the user clear the selected value.

Usage

After installation, you can start building with this component using the following basic elements:

import Autocomplete from '@mui/joy/Autocomplete';
import Input from '@mui/joy/Input';

export default function App() {
  return <Autocomplete options={['Option 1', 'Option 2']} />;
}

Basics

The Autocomplete component requires a list of options to be displayed after the textbox is focused. The value must be chosen from a predefined set of allowed values.

Press Enter to start editing

Customization

Options structure

By default, the options accepts an array of string or { label: string }:

const options = [
  { label: 'The Godfather', id: 1 },
  { label: 'Pulp Fiction', id: 2 },
];
// or
const options = ['The Godfather', 'Pulp Fiction'];

However, you can use different structures by providing a getOptionLabel prop:

const options = [
  { title: 'Pulp Fiction', id: 2 },
  // ...
];

<Autocomplete getOptionLabel={option => option.title}>

Option appearance

To customize the appearance of the options, use renderOption prop in combination with the AutocompleteOption component as an option container.

Variants

The autocomplete component supports the four global variants: outlined (default), soft, solid, and plain.

The variant and color values are propagated to the Autocomplete's input and listbox slots.

To customize the variant and color for a specific slot, use slotProps:

<Autocomplete
  variant="plain"
  slotProps={{
    listbox: {
      variant: 'outlined',
    },
  }}
/>

Label

Put an Autocomplete, a FormLabel and a FormHelperText (optional) under a FormControl component to create an accessible autocomplete.

A description for the combo box.
Press Enter to start editing

Decorators

Use startDecorator or endDecorator to insert decorators to the autocomplete.

The Shawshank Redemption
Press Enter to start editing

Controlled states

The component has two states that can be controlled:

  1. the "value" state with the value/onChange props combination. This state represents the value selected by the user, for instance when pressing Enter.
  2. the "input value" state with the inputValue/onInputChange props combination. This state represents the value displayed in the textbox.

These two states are isolated, and should be controlled independently.

value: 'Option 1'

inputValue: ''


Disabled options

Use getOptionDisabled prop to read the options and returns true to disable them.

Press Enter to start editing

Grouped options

You can group the options with the groupBy prop. If you do so, make sure that the options are also sorted with the same dimension that they are grouped by, otherwise, you will notice duplicate headers.

Press Enter to start editing

Loading

It displays a progress state as long as the network request is pending.

Search input

Use freeSolo to create a search input with suggestions experience, for example Google search or react-autowhatever.

User's created option

If you intend to use freeSolo mode for a combo box like experience (an enhanced version of a select element) we recommend setting:

  • selectOnFocus to help the user clear the selected value.
  • clearOnBlur to help the user enter a new value.
  • handleHomeEndKeys to move focus inside the popup with the Home and End keys.
  • A last option, for instance: Add "YOUR SEARCH".

You could also display a dialog when the user wants to add a new value.

Validation

To display invalid state, set the error prop on the FormControl.

Oops! something went wrong.
Press Enter to start editing

Multiple selection

By default, the autocomplete uses Chip component to render the user's selected options.

When the autocomplete is focused, the user can press the backspace to remove the latest selected option from the list.

Inception
Press Enter to start editing

Selected options appearance

Use the renderTag prop to customize the appearance.

Inception

Limit the selected options to be displayed

You can use the limitTags prop to limit the number of displayed options when not focused.

Inception
Forrest Gump
+1
Press Enter to start editing

Sizes

The autocomplete component comes with three sizes out of the box: sm, md (the default), and lg. The size is propagated to internal components, including Input, Chip, and List.

Inception
Inception
Inception

The size can also be controlled at the FormControl.

Inception
This is a small description.
Press Enter to start editing

Custom filter

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

import { createFilterOptions } from '@mui/material/Autocomplete';

Arguments

  1. config (object [optional]):
  • config.ignoreAccents (bool [optional]): Defaults to true. Remove diacritics.
  • config.ignoreCase (bool [optional]): Defaults to true. Lowercase everything.
  • config.limit (number [optional]): Default to null. Limit the number of suggested options to be shown. For example, if config.limit is 100, only the first 100 matching options are shown. It can be useful if a lot of options match and virtualization wasn't set up.
  • config.matchFrom ('any' | 'start' [optional]): Defaults to 'any'.
  • config.stringify (func [optional]): Controls how an option is converted into a string so that it can be matched against the input text fragment.
  • config.trim (bool [optional]): Defaults to false. Remove trailing spaces.

Returns

filterOptions: the returned filter method can be provided directly to the filterOptions prop of the Autocomplete component, or the parameter of the same name for the hook.

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} />;

Advanced filter

For richer filtering mechanisms, like fuzzy matching, 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} />;

CSS variables playground

The Autocomplete component reuses CSS variables from the Input component to give you the consistent customization experience.

The Godfather
Pulp Fiction
<Autocomplete />

CSS variables


Common examples

Hint

The following demo shows how to add a hint feature to the Autocomplete using the filterOptions prop:

Highlighting options

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

GitHub's picker

To reproduce GitHub's label picker, the Autocomplete is rendered inside a Base UI Popper. To remove the popup behavior from the autocomplete, replace the listbox slot with the AutocompleteListbox component.

  • help wanted
  • type: bug

Virtualization

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

Press Enter to start editing

Events

If you would like to prevent the default key handler behavior, you can set the event's defaultMuiPrevented property to true:

<Autocomplete
  onKeyDown={(event) => {
    if (event.key === 'Enter') {
      // Prevent's default 'Enter' behavior.
      event.defaultMuiPrevented = true;
      // your handler code
    }
  }}
/>

Limitations

autocomplete/autofill

By default, the component disables the input autocomplete feature (remembering what the user has typed for a given field in a previous session) with the autoComplete="off" attribute. Google Chrome does not currently support this attribute setting (Issue 587466). A possible workaround is to remove the id to have the component generate a random one.

In addition to remembering past entered values, the browser might also propose autofill suggestions (saved login, address, or payment details). In the event you want the avoid autofill, you can try the following:

  • Name the input without leaking any information the browser can use. For example id="field1" instead of id="country". If you leave the id empty, the component uses a random id.

  • Set autoComplete="new-password" (some browsers will suggest a strong password for inputs with this attribute setting):

    <Autocomplete
      slotProps={{
        input: {
          autoComplete: 'new-password',
        },
      }}
    />
    

Read the guide on MDN for more details.

iOS VoiceOver

VoiceOver on iOS Safari doesn't support the aria-owns attribute very well. You can work around the issue with the disablePortal prop.

<Autocomplete
  slotProps={{
    listbox: {
      disablePortal: true,
    },
  }}
/>

Accessibility

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)

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

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.