react-md
react-md - AutoComplete - Demos

AutoComplete

Note: The AutoComplete is mostly a desktop only component out of the box due to how soft keyboards work on touch devices. If you want to create an AutoComplete on mobile, you should follow the pattern in the Highlight Matches example where the AutoComplete gets moved into a static header and the menu no longer hides on scroll or page resizing.

An AutoComplete is a component that allows for real-time suggestions from a pre-determined list as the user types by filtering data based on the current value. It can also be used to interact with an API that handles the sorting, filtering, matching, etc as well.

This component has been implemented following the combobox widget specifications so it will be fully accessible. It is recommended to also check out the @react-md/form package for additional styling options since it uses the TextField and Listbox components behind the scenes to show matches.

Here's a quick summary of the accessibility features if you don't want to read the combobox info:

  • ArrowDown - keyboard focus the next suggestion (wraps)
  • ArrowUp - keyboard focus the previous suggestion (wraps)
  • Escape - hide suggestions if they were visible. clear text field if the suggestions were hidden
  • Enter - selects the keyboard focused suggestion if there was one. Submits form otherwise
  • alt + ArrowDown - show suggestions if they were hidden and there are suggestions available
  • alt + ArrowUp - hide suggestions if they were visible without selecting a new value

Simple Example

The base requirements for an AutoComplete are to provide an id, a list of data to filter, and a filter behavior/custom function. However, it is recommended to also provide a label or aria-label for additional accessibility and a placeholder value for additional context.

Since there are a lot of different ways to filter, this library will be keeping it simple and only providing two filter functions out of the box:

  • "case-insensitive" (default) - A simple case insensitive filter that will only show results that contain the input's value in order ignoring case
  • "fuzzy" - A fuzzy filter that will show any results that just contain the same letters in any order ignoring case.

To start off simple, the following examples will just filter based off a list of fruits and show these two filter behaviors.

Using Object Data Sets

Since it isn't extremely helpful to only use strings, the AutoComplete can also filter and display a list of objects. The base requirements for an object result is that it should have:

  • a label key or a children key - This is what will be displayed in the suggestions dropdown menu
  • a value key - This is the searchable string that is used for filtering down the data by the current text field's value.

This allows you to have more complex suggestions by being able to render custom styles within the dropdown list, but still being searchable. In addition, you can use all the list item props for adding icons, avatars, or even media in the suggestion list.

You can also customize this behavior a bit by changing the labelKey and valueKey props to be different values if your object is simple and don't want to transform it to match this structure.

Highlight Matches

The AutoComplete also supports some basic support for highlight letters that match the text field's value when the list of data have string labels. This will only work for "case-insensitive" filtering or a custom filter function that ensures that the matches always match all the letters in order.

If you need more robust highlighting, you can also update the getResultLabel prop and implement your own highlighting behavior instead.

No Dessert Chosen