Autocomplete

The Autocomplete component dynamically suggests options as users type into an input field. This enhances user experience by making data entry faster and more accurate, particularly when dealing with large data sets. With multiple selection and customization capabilities, it offers high versatility for a wide range of applications.

This component is built upon fantastic @floating-ui/react library.

Listening to input value changes

Sometimes you need to get to the actual value passed to the input. For example, you might want to use it to make an external API call. In this case, you can use the onInputChange prop to listen to the input value changes.

Caveat When is cleared by default clearable callback the event will be synthetic and will not contain the actual value.


  const clearableCallback = () => {
    onChange?.(null)
    props.onInputChange?.({ target: { value: '' } } as any)
    clearSearch()
  }

Search query

Autocompleting multiple options

With the multiple prop, the Autocomplete component allows for the selection of multiple options, providing a dynamic and versatile user experience. This example also makes use of the onCreate callback, which is triggered when the user selects an option that does not exist in the options list. This callback can be used to create new options on the fly.

Wade Cooper

Arlene Mccoy

In the multiple mode, the value and onChange props adjust their signature as follows:

Property	`!multiple`	`multiple`
value	`T`	`T[]`
onChange	`T => void`	`T[] => void`

For more details, please refer to the properties table.

Component API

The main Autocomplete component. Extends props of InputBase component.

Prop	Default	Description
`options`	`{ label:string, disabled?: boolean }[]`	`T[]` List available options
`value`	—	`T` Current value of input If multiple is set, the type of `value` will be `T[]`
`onChange`	—	`(value: T \| T[] \| null) => void` Change event callback If multiple is set, the type of `value` will be `T[]`
`onCreate`	—	`(title: string) => void` Callback for creating new option
`multiple`	`false`	`boolean` Allow multiple values
`autoHighlight`	`false`	`boolean` Highlight search text fragment in options. Works only with default getOptionLabel
`renderOption`	`_renderOption`	`(props: AutocompleteOptionProps, option: T) => ReactNode` Function rendering option in dropdown. Docs
`renderSelection`	`_renderSelection`	`(option: T) => ReactNode` Function rendering single selection. Docs
`renderTags`	`_renderTags`	`(selected: T[]) => ReactNode` Function rendering option in dropdown. Docs
`getLimitTagsText`	more => `+${more}`	`(more: number) => string` Text to display when the tags are truncated. Also see `limit` prop
`limit`	`3`	`number` Limit of multiple selected to be displayed in input
`defaultTagProps: ChipProps`	—	`ChipProps` Props of the default tags component (Chip). Chip component docs.
`isOptionEqualToValue`	`_isOptionEqualToValue`	`(option: T, value?: T \| null) => boolean` Function to compare option and value.
`getOptionDisabled`	`option => option.disabled`	`(option: T) => boolean` Getter for option disabled state.
`getOptionLabel`	`option => option.label ?? option`	`(option: T) => string` Getter for option label.
`filterOptions`	`_filterOptions`	`( options: T[], filterOptions: AutocompleteFilterOptions ) => T[]` Filter options function. Docs
`textEmpty`	`No options`	`string` Text to display for empty list.
`textNotFound`	`No results found`	`string` Text to display when no options match search.
`textCreate`	`Create`	`string` Text to display when no options matches search and `onCreate` is provided. Precedes quoted search query like so: `Create "${query}"`
`textLoading`	`Loading...`	`string` Text to display for loading state input. Replaces `placeholder` for the duration of loading.
`textClear`	`Clear`	`string` Text to display as HTML "title" of clear button.
`maxHeight`	`500`	`number \| string \| "available"` How heigh should dropdown list be? Either provide a number of pixels or a string like `1rem`, `20vh`, etc. The `available` option will set the max height of the dropdown to the available height of the screen.
`zIndex`	—	`{ list?: number}` Escape hatch for z-index of dropdown list. Helpful when using with modals and drawers that might have their own, higher z-index.
`filterSelectedOptions`	`false`	`boolean` Should filter out selected options from options list

Default option shape. You can provide your own option shape by passing it to component.

Prop	Default	Description
`label`	`option.label ?? option`	`React.ReactNode` Label of option
`disabled`	—	`boolean` Option disabled state, used by `isOptionDisabled`

Autocomplete

Listening to input value changes

Autocompleting multiple options

Component API

Autocomplete

AutocompleteOptionType