---
title: Autocomplete
description: An autocomplete combines a select with filtering, allowing users to search and select from a list of options
links:
  rac: Select
  source: autocomplete/autocomplete.tsx
  styles: autocomplete.css
  storybook: Components/Pickers/Autocomplete
---

## Usage

```tsx
import { Autocomplete, useFilter } from "@heroui/react";
```

<ComponentPreview name="autocomplete-default" />

## Anatomy

```tsx
import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react";

export default () => (
  <Autocomplete>
    <Label />
    <Autocomplete.Trigger>
      <Autocomplete.Value />
      <Autocomplete.ClearButton />
      <Autocomplete.Indicator />
    </Autocomplete.Trigger>
    <Description />
    <Autocomplete.Popover>
      <Autocomplete.Filter>
        <SearchField>
          <SearchField.Group>
            <SearchField.SearchIcon />
            <SearchField.Input />
          </SearchField.Group>
        </SearchField>
        <ListBox>
          <ListBox.Item>
            <Label />
            <ListBox.ItemIndicator />
          </ListBox.Item>
        </ListBox>
      </Autocomplete.Filter>
    </Autocomplete.Popover>
  </Autocomplete>
);
```

## Examples

### Variants

The Autocomplete component supports two visual variants:

- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components

<ComponentPreview name="autocomplete-variants" />

### Full Width

<ComponentPreview name="autocomplete-full-width" />

### With Description

<ComponentPreview name="autocomplete-with-description" />

### Required

<ComponentPreview name="autocomplete-required" />

### Disabled

<ComponentPreview name="autocomplete-disabled" />

### With Disabled Options

<ComponentPreview name="autocomplete-with-disabled-options" />

### Allows Empty Collection

The `allowsEmptyCollection` prop enables the autocomplete to function even when there are no items in the collection. This is useful for scenarios where the list might be empty initially or when all items are filtered out.

<ComponentPreview name="autocomplete-allows-empty-collection" />

### With Sections

<ComponentPreview name="autocomplete-with-sections" />

### Multiple Select

<ComponentPreview name="autocomplete-multiple-select" />

<Callout type="warning">
  In multiple mode, a bare `<Autocomplete.Value />` renders a copy of each selected item's
  `ListBox.Item` children in the trigger, joined with locale-aware separators. Text-only items read
  as plain text, but visual content such as checkboxes or avatars appears once per selected item,
  and render function children are always called with `isSelected: false`.
</Callout>

To display selected values as plain text, use the `selectedText` render prop, which joins the
`textValue` of each selected item:

```tsx
<Autocomplete.Value>
  {({isPlaceholder, defaultChildren, selectedText}) =>
    isPlaceholder ? defaultChildren : selectedText
  }
</Autocomplete.Value>
```

For richer layouts such as removable tags, render your own content from `state.selectedItems` as
shown in the example above.

### Controlled

<ComponentPreview name="autocomplete-controlled" />

### Controlled Multiple

<ComponentPreview name="autocomplete-controlled-multiple" />

### Controlled Open State

<ComponentPreview name="autocomplete-controlled-open-state" />

### Asynchronous Filtering

<ComponentPreview name="autocomplete-asynchronous-filtering" />

### Custom Indicator

<ComponentPreview name="autocomplete-custom-indicator" />

### Custom Value

You can customize the displayed value using render props:

<ComponentPreview name="autocomplete-custom-value" />

### In Surface

When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.

<ComponentPreview name="autocomplete-on-surface" />

### Virtualization

Autocomplete supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.

<ComponentPreview name="autocomplete-virtualization" />

## Advanced Examples

### User Selection

<ComponentPreview name="autocomplete-user-selection" />

### User Selection Multiple

<ComponentPreview name="autocomplete-user-selection-multiple" />

### Location Search

<ComponentPreview name="autocomplete-location-search" />

### Tag Group Selection

<ComponentPreview name="autocomplete-tag-group-selection" />

### Email Recipients

<ComponentPreview name="autocomplete-email-recipients" />

## Customization

### Tailwind CSS

<ComponentPreview name="autocomplete-custom-styles" />

### Global CSS

To customize the Autocomplete component classes, you can use the `@layer components` directive.

[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .autocomplete {
    @apply flex flex-col gap-1;
  }

  .autocomplete__trigger {
    @apply rounded-lg border border-border bg-surface p-2;
  }

  .autocomplete__value {
    @apply text-current;
  }

  .autocomplete__clear-button {
    @apply text-muted hover:text-foreground;
  }

  .autocomplete__indicator {
    @apply text-muted;
  }

  .autocomplete__popover {
    @apply rounded-lg border border-border bg-surface p-2;
  }
}
```

## Styling Reference

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Autocomplete component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)):

#### Base Classes [!toc]

- `.autocomplete` - Base autocomplete container
- `.autocomplete__trigger` - The button that triggers the autocomplete
- `.autocomplete__value` - The displayed value or placeholder
- `.autocomplete__clear-button` - The clear button that removes the selected value
- `.autocomplete__indicator` - The dropdown indicator icon
- `.autocomplete__popover` - The popover container
- `.autocomplete__filter` - The filter wrapper

#### Variant Classes [!toc]

- `.autocomplete--primary` - Primary variant with shadow (default)
- `.autocomplete--secondary` - Secondary variant without shadow, suitable for use in surfaces

#### State Classes [!toc]

- `.autocomplete[data-invalid="true"]` - Invalid state
- `.autocomplete__trigger[data-focus-visible="true"]` - Focused trigger state
- `.autocomplete__trigger[data-disabled="true"]` - Disabled trigger state
- `.autocomplete__value[data-placeholder="true"]` - Placeholder state
- `.autocomplete__clear-button[data-empty="true"]` - Clear button hidden when no selection
- `.autocomplete__indicator[data-open="true"]` - Open indicator state

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
- **Disabled**: `:disabled` or `[data-disabled="true"]` on autocomplete
- **Open**: `[data-open="true"]` on indicator

## API Reference

### Autocomplete

| Prop            | Type                                    | Default            | Description                                              |
| --------------- | --------------------------------------- | ------------------ | -------------------------------------------------------- |
| `placeholder`   | `string`                                | `'Select an item'` | Temporary text that occupies the autocomplete when it is empty |
| `selectionMode` | `"single" \| "multiple"`                | `"single"`         | Whether single or multiple selection is enabled          |
| `allowsEmptyCollection` | `boolean`                        | `false`            | Whether the autocomplete allows an empty collection. When true, the autocomplete can function even with no items. |
| `isOpen`        | `boolean`                               | -                  | Sets the open state of the popover (controlled)             |
| `defaultOpen`   | `boolean`                               | -                  | Sets the default open state of the popover (uncontrolled)   |
| `onOpenChange`  | `(isOpen: boolean) => void`             | -                  | Handler called when the open state changes               |
| `disabledKeys`  | `Iterable<Key>`                         | -                  | Keys of disabled items                                   |
| `isDisabled`    | `boolean`                               | -                  | Whether the autocomplete is disabled                           |
| `value`         | `Key \| Key[] \| null`                  | -                  | Current value (controlled)                               |
| `defaultValue`  | `Key \| Key[] \| null`                  | -                  | Default value (uncontrolled)                             |
| `onChange`      | `(value: Key \| Key[] \| null) => void` | -                  | Handler called when the value changes                    |
| `isRequired`    | `boolean`                               | -                  | Whether user input is required                           |
| `isInvalid`     | `boolean`                               | -                  | Whether the autocomplete value is invalid                      |
| `name`          | `string`                                | -                  | The name of the input, used when submitting an HTML form |
| `fullWidth`     | `boolean`                               | `false`             | Whether the autocomplete should take full width of its container |
| `variant`       | `"primary" \| "secondary"`             | `"primary"`         | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `className`     | `string`                                | -                  | Additional CSS classes                                   |
| `children`      | `ReactNode \| RenderFunction`           | -                  | Autocomplete content or render function                        |

### Autocomplete.Trigger

| Prop        | Type                          | Default | Description                        |
| ----------- | ----------------------------- | ------- | ---------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes             |
| `children`  | `ReactNode \| RenderFunction` | -       | Trigger content or render function |

### Autocomplete.Value

| Prop        | Type                          | Default | Description                      |
| ----------- | ----------------------------- | ------- | -------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes           |
| `children`  | `ReactNode \| RenderFunction` | -       | Value content or render function |

### Autocomplete.Indicator

| Prop        | Type        | Default | Description              |
| ----------- | ----------- | ------- | ------------------------ |
| `className` | `string`    | -       | Additional CSS classes   |
| `children`  | `ReactNode` | -       | Custom indicator content |

### Autocomplete.ClearButton

| Prop        | Type                          | Default | Description                      |
| ----------- | ----------------------------- | ------- | -------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes           |
| `onClick`   | `(e: MouseEvent) => void`     | -       | Handler called when button is clicked |
| `ref`       | `RefObject<HTMLButtonElement>` | -       | Ref to the clear button element  |

### Autocomplete.Popover

| Prop        | Type                                                                                                                                                                                                                                                                                                                     | Default    | Description                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -          | Additional CSS classes                           |
| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -          | Content children                                 |

### Autocomplete.Filter

| Prop         | Type                                           | Default | Description                      |
| ------------ | ---------------------------------------------- | ------- | -------------------------------- |
| `filter`     | `(text: string, input: string) => boolean`     | -       | Custom filter function           |
| `inputValue` | `string`                                       | -       | Controlled input value          |
| `onInputChange` | `(value: string) => void`                  | -       | Handler called when input value changes |
| `children`   | `ReactNode`                                    | -       | Filter content (SearchField and ListBox) |

### useFilter Hook

The `useFilter` hook from React Aria provides filtering functions for autocomplete functionality.

```tsx
import {useFilter} from "@heroui/react";

const {contains} = useFilter({sensitivity: "base"});

<Autocomplete.Filter filter={contains}>
  <SearchField>...</SearchField>
  <ListBox>...</ListBox>
</Autocomplete.Filter>
```

**Options:**

| Option        | Type                                                         | Default      | Description                     |
| ------------- | ------------------------------------------------------------ | ------------ | ------------------------------- |
| `sensitivity` | `"base" \| "accent" \| "case" \| "variant"`                  | `"base"`     | Locale sensitivity for matching |

**Returns:**

| Function        | Type                                                | Description                     |
| --------------- | --------------------------------------------------- | ------------------------------- |
| `contains`      | `(string: string, substring: string) => boolean`          | Returns whether a string contains a given substring |
| `startsWith`    | `(string: string, substring: string) => boolean`          | Returns whether a string starts with a given substring    |
| `endsWith`      | `(string: string, substring: string) => boolean`          | Returns whether a string ends with a given substring     |

### Render Props

When using render functions with Autocomplete.Value, these values are provided:

| Prop              | Type            | Description                                                                                                                     |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `defaultChildren` | `ReactNode`     | The default rendered value. In multiple mode this is a copy of each selected item's children joined with locale-aware separators |
| `isPlaceholder`   | `boolean`       | Whether the value is a placeholder                                                                                              |
| `state`           | `SelectState`   | The state of the autocomplete. Use `state.selectedItems` for the selected collection nodes                                      |
| `selectedItems`   | `(T \| null)[]` | The values of the currently selected items                                                                                      |
| `selectedText`    | `string`        | The `textValue` of the selected items joined with locale-aware separators                                                        |

## Accessibility

The Autocomplete component implements the ARIA select pattern with filtering and provides:

- Full keyboard navigation support
- Screen reader announcements for selection changes
- Proper focus management
- Support for disabled states
- Search functionality with filtering
- HTML form integration

For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html).

## Related Components

<RelatedComponents component="autocomplete" />
