Skip to content

Autocomplete

Alpha

The Autocomplete components are used to render a text input that allows a user to quickly filter through a list of options to pick one or more values. It is comprised of an Autocomplete.Input component that a user types into, and a Autocomplete.Menu component that displays the list of selectable values.

Basic Example

Autocomplete.Input

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

The default input rendered is the TextInput component. A different text input component may be rendered by passing a different component to the as prop.

The Autocomplete.Input should not be rendered without a <label> who's htmlFor prop matches the Autocomplete.Input's id prop

Component Props

Autocomplete.Input accepts the same props as a native <input />. The other props of Autocomplete.Input depend on what component is passed to the as prop. The default value for as is TextInput

Example: Passing a custom text input

In this example, we're passing a TextInputWithTokens component

Autocomplete.Overlay

The Autocomplete.Overlay wraps the Autocomplete.Menu to display it in an Overlay component. Most Autocomplete implementations will use the Autocomplete.Overlay component, but there could be special cases where the Autocomplete.Menu should be rendered directly after the Autocomplete.Input (for example: an Autocomplete that is already being rendered in an Overlay).

Component Props

AutocompleteOverlay

PropTypeDefaultDescription
aria-labelledby Requiredany
menuAnchorRef anyThe ref of the element that the position of the menu is based on. By default, the menu is positioned based on the text input
overlayProps Partial<OverlayProps>Props to be spread on the internal `Overlay` component.

Example: Without Autocomplete.Overlay

Autocomplete.Menu

The Autocomplete.Menu component renders a list of selectable options in a non-modal dialog. The list is filtered and sorted to make it as easy as possible to find the option/s that a user is looking for.

The Autocomplete.Menu component should be passed an aria-labelledby prop that matches the id prop of the <label> associated with the Autocomplete.Input

Component Props

AutocompleteMenu

PropTypeDefaultDescription
items RequiredT[]The options for field values that are displayed in the dropdown menu. One or more may be selected depending on the value of the `selectionVariant` prop.
selectedItemIds Required(string | number)[]The IDs of the selected items
aria-labelledby Requiredany
addNewItem Omit<T, "id" | "onAction" | "leadingVisual"> & { handleAddItem: (item: Omit<T, "onAction" | "leadingVisual">) => void; }A menu item that is used to allow users make a selection that is not available in the array passed to the `items` prop. This menu item gets appended to the end of the list of options.
emptyStateText anyNo selectable optionsThe text that appears in the menu when there are no options in the array passed to the `items` prop.
filterFn (item: T, i: number) => booleanA custom function used to filter the options in the array passed to the `items` prop. By default, we filter out items that don't match the value of the autocomplete text input. The default filter is not case-sensitive.
loading booleanWhether the data is loaded for the menu items
sortOnCloseFn (itemIdA: string | number, itemIdB: string | number) => numberThe sort function that is applied to the options in the array passed to the `items` prop after the user closes the menu. By default, selected items are sorted to the top after the user closes the menu.
selectionVariant "multiple" | "single"singleWhether there can be one item selected from the menu or multiple items selected from the menu
onOpenChange (open: boolean) => voidFunction that gets called when the menu is opened or closed
onSelectedChange OnSelectedChange<T>The function that is called when an item in the list is selected or deselected
customScrollContainerRef anyIf the menu is rendered in a scrolling element other than the `Autocomplete.Overlay` component, pass the ref of that element to `customScrollContainerRef` to ensure the container automatically scrolls when the user highlights an item in the menu that is outside the scroll container

Customizing how menu items are rendered

By default, menu items are just 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. However, the renderGroup, groupMetadata, and renderItem props have not been implemented yet.

Example: Render items using ActionList.Item props

Sorting menu items

Items can be displayed in any order that makes sense, but the Autocomplete.Menu component comes with a default sort behavior to make it easy to find selected items. The default behavior is to sort selected items to the top of the list after the menu has been closed.

A function may be passed to the sortOnCloseFn prop if this default sorting logic is not helpful for your use case. The sort function will be only be called after the menu is closed so that items don't shift while users are trying to make a selection.

Example: When the menu is re-opened, selected items get sorted to the end

Filtering items

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.

A function may be passed to the filterFn prop if this default filtering behavior does not make sense for your use case.

Example: Show any items that contain the input value

Rendering the menu without an Autocomplete.Overlay

If a Autocomplete.Menu is rendered without an Autocomplete.Overlay inside of a scrollable container, the ref of the scrollable container must be passed to the customScrollContainerRef to ensure that highlighted items are always scrolled into view.

Example: Rendered without Autocomplete.Overlay with a customScrollContainerRef

More examples

Select multiple values

Select multiple values - new values can be added