---
title: Autocomplete
description: An input that suggests options as you type.

links:
  doc: https://base-ui.com/react/components/autocomplete#api-reference
---

<ComponentPreview name="p-autocomplete-1" />

## Installation

<CodeTabs>

<TabsList>
  <TabsTab value="cli">CLI</TabsTab>
  <TabsTab value="manual">Manual</TabsTab>
</TabsList>

<TabsPanel value="cli">

```bash
npx shadcn@latest add @coss/autocomplete
```

</TabsPanel>

<TabsPanel value="manual">

<Steps>

<Step>Install the following dependencies:</Step>

```bash
npm install @base-ui/react
```

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="autocomplete" title="components/ui/autocomplete.tsx" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsPanel>

</CodeTabs>

## Usage

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
```

```tsx
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Autocomplete items={items}>
  <AutocompleteInput placeholder="Search..." />
  <AutocompletePopup>
    <AutocompleteEmpty>No results found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => <AutocompleteItem key={item.value} value={item}>{item.label}</AutocompleteItem>}
    </AutocompleteList>
  </AutocompletePopup>
</Autocomplete>
```

## API Reference

### Autocomplete

The root autocomplete component. Manages the autocomplete state and provides context to child components.

| Prop       | Type                                      | Description                                         |
| ---------- | ----------------------------------------- | --------------------------------------------------- |
| `items`    | `readonly unknown[]`                      | The array of items to display in the autocomplete   |
| `open`     | `boolean`                                 | Controls whether the popup is open                  |
| `...props` | `React.ComponentProps<typeof Autocomplete>` | All Base UI Autocomplete props are supported        |

### AutocompleteInput

The input field component with extended features for size variants and addon support.

| Prop           | Type                              | Default     | Description                                                                                      |
| -------------- | --------------------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `size`         | `"sm" \| "default" \| "lg"`       | `"default"` | The size variant of the input field                                                              |
| `startAddon`   | `React.ReactNode`                 | -           | Element to display at the start (left side) of the input, such as an icon                        |
| `showTrigger`  | `boolean`                         | `false`     | Whether to display a trigger button (chevron icon) on the right side of the input                |
| `showClear`    | `boolean`                         | `false`     | Whether to display a clear button (X icon) on the right side of the input when there is a value |
| `triggerProps`  | `Autocomplete.Trigger.Props`     | -           | Props forwarded to the internal trigger button, useful for overriding `aria-label`               |
| `clearProps`    | `Autocomplete.Clear.Props`       | -           | Props forwarded to the internal clear button, useful for overriding `aria-label`                 |
| `className`    | `string`                          | -           | Additional CSS classes to apply to the component                                                 |
| `...props`     | Base UI Autocomplete Input props  | -           | All standard autocomplete input attributes are supported                                         |

### AutocompletePopup

The popup container that displays the autocomplete suggestions.

| Prop           | Type                                          | Description                                      |
| -------------- | --------------------------------------------- | ------------------------------------------------ |
| `className`    | `string`                                      | Additional CSS classes to apply to the component |
| `portalProps`  | `Autocomplete.Portal.Props`                   | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Combobox portal API (autocomplete reuses it) |
| `...props`     | Base UI Autocomplete Popup props              | All standard autocomplete popup attributes are supported |

### AutocompleteList

A scrollable container for autocomplete items.

| Prop        | Type                                     | Description                                      |
| ----------- | ---------------------------------------- | ------------------------------------------------ |
| `className` | `string`                                 | Additional CSS classes to apply to the component |
| `...props`  | Base UI Autocomplete List props          | All standard autocomplete list attributes are supported |

### AutocompleteItem

An individual selectable autocomplete item.

| Prop        | Type                                     | Description                                      |
| ----------- | ---------------------------------------- | ------------------------------------------------ |
| `value`     | `unknown`                                | The value of the item                            |
| `className` | `string`                                 | Additional CSS classes to apply to the component |
| `...props`  | Base UI Autocomplete Item props          | All standard autocomplete item attributes are supported |

### AutocompleteEmpty

Displays a message when no results are found.

| Prop        | Type                                      | Description                                      |
| ----------- | ----------------------------------------- | ------------------------------------------------ |
| `className` | `string`                                  | Additional CSS classes to apply to the component |
| `...props`  | Base UI Autocomplete Empty props          | All standard autocomplete empty attributes are supported |

### AutocompleteGroup

Groups related autocomplete items together.

| Prop        | Type                                      | Description                                      |
| ----------- | ----------------------------------------- | ------------------------------------------------ |
| `items`     | `readonly unknown[]`                      | The array of items in this group                 |
| `className` | `string`                                  | Additional CSS classes to apply to the component |
| `...props`  | Base UI Autocomplete Group props          | All standard autocomplete group attributes are supported |

### AutocompleteGroupLabel

Displays a label for an autocomplete group.

| Prop        | Type                                           | Description                                      |
| ----------- | ---------------------------------------------- | ------------------------------------------------ |
| `className` | `string`                                       | Additional CSS classes to apply to the component |
| `...props`  | Base UI Autocomplete Group Label props         | All standard autocomplete group label attributes are supported |

### AutocompleteCollection

Used to wrap items within a group for rendering.

| Prop        | Type                                           | Description                                      |
| ----------- | ---------------------------------------------- | ------------------------------------------------ |
| `...props`  | Base UI Autocomplete Collection props          | All standard autocomplete collection attributes are supported |

## Examples

### Disabled

<ComponentPreview name="p-autocomplete-2" />

### Small Size

<ComponentPreview name="p-autocomplete-3" />

### Large Size

<ComponentPreview name="p-autocomplete-4" />

### With Label

<ComponentPreview name="p-autocomplete-5" />

### Inline Autocomplete

Autofill the input with the highlighted item while navigating with arrow keys.

<ComponentPreview name="p-autocomplete-6" />

### Auto Highlight

Automatically highlight the first matching option.

<ComponentPreview name="p-autocomplete-7" />

### With Clear Button

<ComponentPreview name="p-autocomplete-8" />

### With Trigger and Clear Buttons

<ComponentPreview name="p-autocomplete-9" />

### With Start Addon

Display an icon or other element at the start of the input using the `startAddon` prop.

<ComponentPreview name="p-autocomplete-14" />

### With Groups

<ComponentPreview name="p-autocomplete-10" />

### With Limit Results

<ComponentPreview name="p-autocomplete-11" />

### Async Search

<ComponentPreview name="p-autocomplete-12" />

### Form Integration

<ComponentPreview name="p-autocomplete-13" />