Skip to content

Autocomplete

Alpha

Autocomplete inputs allow users to quickly filter through a list of options to pick one or more values for a field.

 React

Overview

The autocomplete component is an enhanced text input that makes it easier to choose one or more values from a long list of options. The list of options is displayed when a user focuses the input. It is similar to a SelectPanel, except the text input is rendered inline instead of being shown after clicking a button.

Anatomy

An autocomplete is made up of an input and a menu of options.

autocomplete anatomy diagram

Usage

Text input

open autocomplete with menu de-emphasized

The text input is used to filter the options in the menu. It is also used to show the selected value (or values).

This input follows the same design guidelines as a text input that is not part of an autocomplete.

The menu is a list of options for the field's value. It appears as a list in a non-modal dialog that the user may select one or more values from.

open autocomplete with text input de-emphasized

menu opened, showing an empty state

When there are no possible selections that can be made, a message is displayed that explains there are no possible options to select. The default message is "No selectable options".

menu opened, showing an empty state

If a user is not limited to a pre-defined list of options, an additional item can be rendered in the menu to select the value that has been typed into the text input.

menu opened, showing an empty state

A loading indicator should be displayed while the data for the list of options is being populated. The loading indicator helps the user understand that the list is not empty, it's just not done loading.

By default, menu items are rendered as a single line of text. The list in the menu is rendered using the Action List component, so menu items can be rendered with all of the same options as Action List items.

Sort and filter behavior

Sorting

The order of the items should not be random: they should be ordered in a way that makes it easy for a user to find a specific value. This could mean items may be ranked by how likely a user is to pick that option (for example, ordering labels by the number of times they've been used in that repository), or it could simply be in alphabetical order.

If multiple values can be selected, the default behavior is to move the selected items to the top of the list after the menu is closed. If this sorting logic is not helpful for your use case, you may override this behavior with a more appropriate sorting logic.

Filtering

By default, menu items are filtered based on whether or not they match the value of the text input. The default filter is case-insensitive.

Custom filtering logic can be applied if the default filtering behavior does not make sense for your use case. However, it is strongly discouraged to disable filtering entirely.