Autocomplete

An autocomplete combines a text input with a listbox, allowing users to filter a list of options to items matching a query.


Installation

npx nextui-cli@latest add autocomplete
No need to install this package if @nextui-org/react is already installed globally.

Import

NextUI exports 3 autocomplete-related components:

  • Autocomplete: The main component, which is a wrapper for the other components.
  • AutocompleteSection: The component that contains a group of autocomplete items.
  • AutocompleteItem: The component that represents a autocomplete item.

Usage

Dynamic items

Autocomplete follows the Collection Components API, accepting both static and dynamic collections.

  • Static: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
  • Dynamic: The example below can be used when the options come from an external data source such as an API call, or update over time.

Disabled

Disabled Items

You can disable specific items by using the disabledKeys property.

Required

If you pass the isRequired property to the autocomplete, it will have a danger asterisk at the end of the label and the autocomplete will be required.

Read Only

If you pass the isReadOnly property to the Autocomplete, the Listbox will open to display all available options, but users won't be able to select any of the listed options.

Sizes

Colors

Variants

Label Placements

You can change the position of the label by setting the labelPlacement property to inside, outside or outside-left.

Note: If the label is not passed, the labelPlacement property will be outside by default.

Start Content

You can use the startContent and endContent properties to add content to the start and end of the autocomplete.

Item Start & End Content

Since the Autocomplete component uses the Listbox component under the hood, you can use the startContent and endContent properties of the AutocompleteItem component to add content to the start and end of the autocomplete item.

Custom Value

By default, Autocomplete doesn't allow users to specify a value that doesn't exist in the list of options and will revert the input value to the current selected value on blur. By specifying allowsCustomValue, this behavior is suppressed and the user is free to enter any value within the field.

Custom Selector Icon

By default, Autocomplete uses a chevron-down icon as the selector icon which rotates when the autocomplete is open. You can customize this icon by passing a custom one to the selectorIcon property.

Note: Use the disableSelectorIconRotation property to disable the rotation of the icon.

Without Scroll Shadow

Autocomplete component uses the ScrollShadow under the hood to show a shadow when the autocomplete content is scrollable. You can disable this shadow by passing using the scrollShadowProps property.

Note: You can also use the showScrollIndicators property to disable the scroll indicators.

With Description

You can add a description to the autocomplete by passing the description property.

With Error Message

You can combine the isInvalid and errorMessage properties to show an invalid autocomplete.

Events

The Autocomplete component supports selection via mouse, keyboard, and touch. You can handle all of these via the onSelectionChange prop. Autocomplete will pass the selected key to the onSelectionChange handler. Additionally, ComboBox accepts an onInputChange prop which is triggered whenever the value is edited by the user, whether through typing or option selection.

The example below uses onSelectionChange and onInputChange to update the selection and input value stored in React state.

Controlled

You can use the selectedKey and onSelectionChange properties to control the select value.

Fully Controlled

By passing in inputValue, selectedKey, and items to the Autocomplete you can control exactly what your Autocomplete should display.

The following example shows how you would create a controlled Autocomplete, controlling everything from the selected value selectedKey to the combobox options items.

We recommend using the useFilter hook from @react-aria/i18n to manage the filtering of the items.

npm install @react-aria/i18n
import {useFilter} from "@react-aria/i18n";

Note: It is important to note that you don't have to control every single aspect of a Autocomplete. If you decide to only control a single property of the Autocomplete, be sure to provide the change handler for that prop as well e.g. controlling selectedKey would require onSelectionChange.

Custom Items

You can customize the autocomplete items by modifying the AutocompleteItem children.

Custom Filtering

By default, Autocomplete uses a "contains" function from useFilter to filter the list of options. This can be overridden using the defaultFilter prop, or by using the items prop to control the filtered list. When items is provided rather than defaultItems, Autocomplete does no filtering of its own.

The following example uses the defaultFilter prop to filter the list of options using a custom filter function.

Asynchronous Filtering

Autocomplete supports asynchronous filtering, in the example below we are using the useAyncList function from react-aria to handle asynchronous loading and filtering of data from a server.

npm install @react-stately/data
import {useAsyncList} from "@react-stately/data";

Asynchronous Loading

Autocomplete supports asynchronous loading, in the example below we are using a custom hook to fetch the Pokemon API data in combination with the useInfiniteScroll hook to load more data when the user reaches the end of the list.

The isLoading prop is used to show a loading indicator instead of the selector icon when the data is being fetched.

npm install @nextui-org/use-infinite-scroll
import {useInfiniteScroll} from "@nextui-org/use-infinite-scroll";

With Sections

You can use the AutocompleteSection component to group autocomplete items.

Custom Sections Style

You can customize the sections style by using the classNames property of the AutocompleteSection component.

Customizing the Autocomplete

You can customize any slot of the autocomplete by using the classNames property. Autocomplete component also provides the popoverProps, listboxProps, inputProps properties to customize the popover, listbox and input components.

Slots

  • base: The main wrapper of the autocomplete. This wraps the input and popover components.
  • listboxWrapper: The wrapper of the listbox. This wraps the listbox component, this slot is used on top of the scroll shadow component.
  • listbox: The listbox component. This is the component that wraps the autocomplete items.
  • popoverContent: The popover content slot. Use this to modify the popover content styles.
  • endContentWrapper: The wrapper of the end content. This wraps the clear button and selector button.
  • clearButton: The clear button slot.
  • selectorButton: The selector button slot.

Data Attributes

Autocomplete has the following attributes on the base element:

  • data-invalid: When the autocomplete is invalid. Based on isInvalid prop.
  • data-open: Indicates if the autocomplete's popover is open.

Autocomplete has the following attributes on the selectorButton element:

  • data-open: Indicates if the autocomplete's popover is open.

Autocomplete has the following attributes on the clearButton element:

  • data-visible: Indicates if the autocomplete's clear button is visible. By default it is visible when hovering the autocomplete and when the autocomplete has a value (desktop), or when the autocomplete has a value (mobile).

AutocompleteItem has the following attributes on the base element:

  • data-disabled: When the autocomplete item is disabled. Based on autocomplete disabledKeys prop.
  • data-selected: When the autocomplete item is selected. Based on autocomplete selectedKey prop.
  • data-hover: When the autocomplete item is being hovered. Based on useHover
  • data-pressed: When the autocomplete item is pressed. Based on usePress
  • data-focus: When the autocomplete item is being focused. Based on useFocusRing.
  • data-focus-visible: When the autocomplete item is being focused with the keyboard. Based on useFocusRing.

Accessibility

  • Support for filtering a list of options by typing
  • Support for selecting a single option
  • Support for disabled options
  • Support for groups of items in sections
  • Support for custom user input values
  • Support for controlled and uncontrolled options, selection, input value, and open state
  • Support for custom filter functions
  • Async loading and infinite scrolling support
  • Support for virtualized scrolling for performance with long lists
  • Exposed to assistive technology as a combobox with ARIA
  • Labeling support for accessibility
  • Required and invalid states exposed to assistive technology via ARIA
  • Support for mouse, touch, and keyboard interactions
  • Keyboard support for opening the combo box list box using the arrow keys, including automatically focusing the first or last item accordingly
  • Support for opening the list box when typing, on focus, or manually
  • Handles virtual clicks on the input from touch screen readers to toggle the list box
  • Virtual focus management for combo box list box option navigation
  • Hides elements outside the input and list box from assistive technology while the list box is open in a portal
  • Custom localized announcements for option focusing, filtering, and selection using an ARIA live region to work around VoiceOver bugs
  • Support for description and error message help text linked to the input via ARIA

API

Autocomplete Props

AttributeTypeDescriptionDefault
children*ReactNode[]The children to render. Usually a list of AutocompleteItem and AutocompleteSection elements.-
labelReactNodeThe content to display as the label.-
namestringThe name of the input element, used when submitting an HTML form. See MDN.-
variantflat | bordered | faded | underlinedThe variant of the Autocomplete.flat
colordefault | primary | secondary | success | warning | dangerThe color of the Autocomplete.default
sizesm | md | lgThe size of the Autocomplete.md
radiusnone | sm | md | lg | fullThe radius of the Autocomplete.-
itemsIterable<T>The list of Autocomplete items. (controlled)-
defaultItemsIterable<T>The list of Autocomplete items (uncontrolled).-
inputValuestringThe value of the Autocomplete input (controlled).-
defaultInputValuestringThe value of the Autocomplete input (uncontrolled).-
allowsCustomValuebooleanWhether the Autocomplete allows a non-item matching input value to be set.false
allowsEmptyCollectionbooleanWhether the autocomplete allows the menu to be open when the collection is empty.true
shouldCloseOnBlurbooleanWhether the Autocomplete should close when the input is blurred.true
placeholderstringTemporary text that occupies the text input when it is empty.-
descriptionReactNodeA description for the field. Provides a hint such as specific requirements for what to choose.-
menuTriggerfocus | input | manualThe action that causes the menu to open.focus
labelPlacementinside | outside | outside-leftThe position of the label.inside
selectedKeyReact.KeyThe currently selected key in the collection (controlled).-
defaultSelectedKeyReact.KeyThe initial selected key in the collection (uncontrolled).-
disabledKeysall | React.Key[]The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.-
errorMessageReactNode | ((v: ValidationResult) => ReactNode)An error message to display below the field.-
validate(value: { inputValue: string, selectedKey: React.Key }) => ValidationError | true | null | undefinedValidate input values when committing (e.g. on blur), and return error messages for invalid values.-
startContentReactNodeElement to be rendered in the left side of the Autocomplete.-
endContentReactNodeElement to be rendered in the right side of the Autocomplete.-
autoFocusbooleanWhether the Autocomplete should be focused on render.false
defaultFilter(textValue: string, inputValue: string) => booleanThe filter function used to determine if a option should be included in the Autocomplete list.-
filterOptionsIntl.CollatorOptionsThe options used to create the collator used for filtering.{ sensitivity: 'base'}
isReadOnlybooleanWhether the Autocomplete is read only.false
isRequiredbooleanWhether the Autocomplete is required.false
isInvalidbooleanWhether the Autocomplete is invalid.false
isDisabledbooleanWhether the Autocomplete is disabled.false
fullWidthbooleanWhether the input should take up the width of its parent.true
selectorIconReactNodeThe icon that represents the autocomplete open state. Usually a chevron icon.-
clearIconReactNodeThe icon to be used in the clear button. Usually a cross icon.-
showScrollIndicatorsbooleanWhether the scroll indicators should be shown when the listbox is scrollable.true
scrollRefReact.RefObject<HTMLElement>A ref to the scrollable element.-
inputPropsInputPropsProps to be passed to the Input component.-
popoverPropsPopoverPropsProps to be passed to the Popover component.-
listboxPropsListboxPropsProps to be passed to the Listbox component.-
scrollShadowPropsScrollShadowPropsProps to be passed to the ScrollShadow component.-
selectorButtonPropsButtonPropsProps to be passed to the selector button.-
clearButtonPropsButtonPropsProps to be passed to the clear button.-
isClearablebooleanWhether the clear button should be shown.true
disableClearablebooleanWhether the clear button should be hidden. (Deprecated) Use isClearable instead.false
disableAnimationbooleanWhether the Autocomplete should be animated.true
disableSelectorIconRotationbooleanWhether the select should disable the rotation of the selector icon.false
classNamesRecord<"base"| "listboxWrapper"| "listbox"| "popoverContent" | "endContentWrapper"| "clearButton" | "selectorButton", string>Allows to set custom class names for the Autocomplete slots.-

Autocomplete Events

AttributeTypeDescription
onOpenChange(isOpen: boolean, menuTrigger?: MenuTriggerAction) => voidMethod that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
onInputChange(value: string) => voidHandler that is called when the Autocomplete input value changes.
onSelectionChange(key: React.Key) => voidHandler that is called when the Autocomplete selection changes.
onFocus(e: FocusEvent<HTMLInputElement>) => voidHandler that is called when the Autocomplete input is focused.
onBlur(e: FocusEvent<HTMLInputElement>) => voidHandler that is called when the Autocomplete input is blurred.
onFocusChange(isFocused: boolean) => voidHandler that is called when the Autocomplete input focus changes.
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.
onClose() => voidHandler that is called when the Autocomplete's Popover is closed.

AutocompleteItem Props

Check the ListboxItem props.

AutocompleteItem Events

Check the ListboxItem events.

AutocompleteSection Props

Check the ListboxSection props.


Types

type MenuTriggerAction = "focus" | "input" | "manual";