---
title: Autocomplete
description: Auto Complete provides a searchable dropdown with autocomplete functionality, allowing users to filter and select options as they type.
category: Forms
related: [Select, TextField, SearchField, Dropdown]
commonPatterns: [search-autocomplete, form-autocomplete, create-option-autocomplete]
---

Source: https://clickhouse.design/click-ui/autocomplete

# Autocomplete

Auto Complete is a searchable dropdown component that filters options as users type. It supports creating new options, grouped items, and custom rendering.

| Prop              | Type                                | Default value | Description                                                                                 |
| ----------------- | ----------------------------------- | ------------- | ------------------------------------------------------------------------------------------- |
| value             | `string`                            | `""`          | Current input value of the autocomplete field                                               |
| onSelect          | `(value: string) => void`           | `undefined`   | Callback function called when an option is selected. Receives the selected value.           |
| placeholder       | `string`                            | `undefined`   | Placeholder text displayed when the field is empty                                          |
| options           | `Array<AutoCompleteOptionListItem>` | `[]`          | Array of autocomplete option objects, each with label and value properties                  |
| label             | `ReactNode`                         | `undefined`   | Label text or content displayed above or beside the autocomplete field                      |
| error             | `ReactNode`                         | `undefined`   | Error message or content displayed when validation fails                                    |
| disabled          | `boolean`                           | `false`       | Whether the autocomplete is disabled and cannot be interacted with                          |
| allowCreateOption | `boolean`                           | `false`       | Whether users can create new options by typing values not in the options list               |
| onOpenChange      | `(open: boolean) => void`           | `undefined`   | Callback function called when the dropdown open state changes. Receives the new open state. |

```tsx
import { AutoComplete } from '@clickhouse/click-ui'

<AutoComplete
value={value}
onSelect={setValue}
placeholder="Search options..."
options={[
  { label: 'Option 1', value: 'option1' },
  { label: 'Option 2', value: 'option2' }
]}
/>
```

## Quick start

```tsx
import { AutoComplete } from '@clickhouse/click-ui'
import { useState } from 'react'

function MyAutoComplete() {
const [value, setValue] = useState('')
return (
  <AutoComplete
    value={value}
    onSelect={setValue}
    placeholder="Search options..."
    options={[
      { label: 'Option 1', value: 'option1' },
      { label: 'Option 2', value: 'option2' },
    ]}
  />
)
}
```

## Related components

- **Select**: For dropdown selection without search functionality.
- **TextField**: For basic text input without autocomplete.
- **SearchField**: For search inputs with icon.
- **Dropdown**: For dropdown menus without autocomplete.

## Common use cases

### Basic autocomplete

```tsx
import { AutoComplete } from '@clickhouse/click-ui'
import { useState } from 'react'

function BasicAutoComplete() {
const [value, setValue] = useState('')
return (
  <AutoComplete
    value={value}
    onSelect={setValue}
    placeholder='Search options...'
    options={[
      { label: 'Apple', value: 'apple' },
      { label: 'Banana', value: 'banana' },
    ]}
  />
)
}
```

## Using with Children

You can also use AutoComplete with children for more control:

| Prop               | Type                            | Default value | Description |
| ------------------ | ------------------------------- | ------------- | ----------- |
| AutoComplete.Item  | Individual option item          |               |             |
| AutoComplete.Group | Group of options with a heading |               |             |

```tsx
<AutoComplete value={value} onSelect={setValue}>
<AutoComplete.Group heading="Group 1">
  <AutoComplete.Item value="option1" label="Option 1" />
  <AutoComplete.Item value="option2" label="Option 2" />
</AutoComplete.Group>
<AutoComplete.Group heading="Group 2">
  <AutoComplete.Item value="option3" label="Option 3" />
</AutoComplete.Group>
</AutoComplete>
```

## Variants

### With groups

### With create option

```tsx
import { AutoComplete } from '@clickhouse/click-ui'
import { useState } from 'react'

function CreateOptionAutoComplete() {
const [value, setValue] = useState('')
return (
  <AutoComplete
    value={value}
    onSelect={setValue}
    placeholder='Type to search or create...'
    allowCreateOption
    options={[
      { label: 'Existing Option 1', value: 'opt1' },
      { label: 'Existing Option 2', value: 'opt2' },
    ]}
  />
)
}
```