---
title: 'Autocomplete'
type: 'component'
status: 'stable'
slug: /components/autocomplete/
github: 'https://github.com/contentful/forma-36/tree/main/packages/components/autocomplete'
storybook: 'https://f36-storybook.contentful.com/?path=/story/components-autocomplete--basic'
typescript: ./src/Autocomplete.tsx
---

Search through a long list of options.

## Import

```jsx static=true
import { Autocomplete } from '@contentful/f36-components';
// or
import { Autocomplete } from '@contentful/f36-autocomplete';
```

## Examples

### Basic usage

The Autocomplete requires 3 props to work:

- `items`: It’s an array containing the items that will be shown as selectable options when the user types something in the `TextInput`.
- `onInputValueChange`: This function will be called every time the user types something in the input.
  The component will pass the `item`, which the filter method is currently iterating over, and the `inputValue` prop of the `TextInput` component.
- `onSelectItem`: This function is called when the user selects one of the options of the list. The component will pass the selected item as an argument to the function.

An `Autocomplete` with a list of spaces will look like this:

```jsx file=./examples/AutocompleteBasicUsageExample.tsx

```

### Using objects as `items`

We showed how to create an Autocomplete with an array of string but it’s also possible to use other types of data as `items`.
A very common way of using the Autocomplete is with objects and for that, with a few changes to the previous example this can be done:

```jsx file=./examples/AutocompleteWithObjectsExample.tsx

```

Both `itemToString` and `renderItem` are necessary when passing objects as items and they both will receive an "item" as an argument.

If you are using Typescript, you can tell the Autocomplete what is the type of your items to make these functions strongly typed.
You can do that by writing the component like this `<Autocomplete<ItemType> {...props}/>`

### Highlighting an item with `getStringMatch`

A common use case for Autocomplete components is to highlight in each suggestion what is typed in the input.
Using the previous example, if a user types "fi" we want to show a list of suggestions where only "fi" is **bold**.
This is possible by using the `renderItem` prop and the `getStringMatch` utility function:

```jsx file=./examples/AutocompleteHighlightingExample.tsx

```

### Selecting multiple items

It is also possible to use the Autocomplete as multiselect. To improve the user experience, you can keep the dropdown open after selection by setting the "closeAfterSelect" property to false.

```jsx file=./examples/AutocompleteMultiSelectionExample.tsx

```

### Using grouped objects as `items`

As an extension of ["Use objects as items" section](#use-objects-as-items), you are also able to use a nested object to group your entries.
The most important part of making this work is the shape of the grouped object. The options themselves work exactly as in the object example and require the `itemToString`
and `renderItem` functions.
Besides the correct shape of the object the Autocomplete component needs to receive the prop `isGrouped`

```jsx file=./examples/AutocompleteWithGroupedItems.tsx

```

### Fully controlled selection from outside

In order to use proper form validation you need to be able to control the actual input field from the autocomplete, because the search query value is not the actual selection. This is done via the selectedItem property.

```jsx file=./examples/ControlledAutocomplete.tsx

```

### Error validation with FormControl

```jsx file=./examples/AutocompleteWithErrorValidationExample.tsx

```

### Fetching async data

```jsx file=./examples/AutocompleteFetchingAsyncDataExample.tsx

```

### Custom icon

Pass a custom icon to the text input, example: to indicate a search input

```jsx file=./examples/CustomIcon.tsx

```

## Props (API reference)

<PropsTable of="Autocomplete" />

## Content guidelines

- Autocomplete label should be short, contain 1 to 3 words
- Label should be written in a sentence case (the first word capitalized, the rest lowercase)

## Accessibility

- dismisses the dropdown when selecting with the enter key