# Autocomplete ยท HeroUI
> An autocomplete combines a select with filtering, allowing users to search and select from a list of options
- Page: https://jiguang132.com/systems/heroui/docs/components/autocomplete
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af
## Import
```tsx
import { Autocomplete, useFilter } from "@heroui/react";
```
### Usage
> Example `autocomplete-default`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Anatomy
Import the Autocomplete component and access all parts using dot notation.
```tsx
import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react";
export default () => (
);
```
### With Description
> Example `autocomplete-with-description`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Multiple Select
> Example `autocomplete-multiple-select`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### With Sections
> Example `autocomplete-with-sections`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### With Disabled Options
> Example `autocomplete-with-disabled-options`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### 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.
> Example `autocomplete-allows-empty-collection`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Custom Indicator
> Example `autocomplete-custom-indicator`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Required
> Example `autocomplete-required`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Full Width
> Example `autocomplete-full-width`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### 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
> Example `autocomplete-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### In Surface
When used inside a [Surface](/systems/heroui/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
> Example `autocomplete-full-width`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Custom Value
You can customize the displayed value using render props:
> Example `autocomplete-user-selection`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Controlled
> Example `autocomplete-controlled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Controlled Multiple
> Example `autocomplete-multiple-select`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Controlled Open State
> Example `autocomplete-controlled-open-state`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Asynchronous Filtering
> Example `autocomplete-asynchronous-filtering`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### 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.
> Example `autocomplete-virtualization`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Disabled
> Example `autocomplete-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
### Advanced Examples
#### User Selection
> Example `autocomplete-user-selection`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
#### User Selection Multiple
> Example `autocomplete-user-selection-multiple`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
#### Location Search
> Example `autocomplete-location-search`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
#### Tag Group Selection
> Example `autocomplete-tag-group-selection`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
#### Email Recipients
> Example `autocomplete-email-recipients`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/autocomplete
## Styling
### Passing Tailwind CSS classes
```tsx
import {Autocomplete, SearchField, ListBox} from "@heroui/react";
function CustomAutocomplete() {
return (
Item 1
);
}
```
### Customizing the component classes
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;
}
.autocomplete__popover-dialog {
@apply outline-none;
}
}
```
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
- `.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__popover-dialog` - Internal dialog wrapper inside the popover for focus management (matches [Popover](/systems/heroui/docs/components/popover) behavior)
- `.autocomplete__filter` - The filter wrapper
#### Variant Classes
- `.autocomplete--primary` - Primary variant with shadow (default)
- `.autocomplete--secondary` - Secondary variant without shadow, suitable for use in surfaces
#### State Classes
- `.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 Props
| 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` | - | 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 Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | ---------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function |
### Autocomplete.Value Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Value content or render function |
### Autocomplete.Indicator Props
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | ------------------------ |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Custom indicator content |
### Autocomplete.ClearButton Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `onClick` | `(e: MouseEvent) => void` | - | Handler called when button is clicked |
| `ref` | `RefObject` | - | Ref to the clear button element |
### Autocomplete.Popover Props
| 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. Wrapped internally in a dialog element for focus management, styled with `.autocomplete__popover-dialog`. |
### Autocomplete.Filter Props
| 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"});
......
```
**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 |
### RenderProps
When using render functions with Autocomplete.Value, these values are provided:
| Prop | Type | Description |
| ----------------- | ------------- | ---------------------------------- |
| `defaultChildren` | `ReactNode` | The default rendered value |
| `isPlaceholder` | `boolean` | Whether the value is a placeholder |
| `state` | `SelectState` | The state of the autocomplete |
| `selectedItems` | `Node[]` | The currently selected items |
## Accessibility
The Autocomplete component implements the ARIA select pattern with filtering and provides:
- Full keyboard navigation support
- Screen reader announcements for selection changes
- Focus management aligned with [Popover](/systems/heroui/docs/components/popover): `Autocomplete.Popover` wraps its content in an internal dialog so touch interactions do not show a stray focus ring on the popover overlay
- Support for disabled states
- Search functionality with filtering
- HTML form integration
Use `autoFocus={false}` on `SearchField` when you want to avoid opening the mobile keyboard as soon as the popover appears. Filtering still works once the user focuses the search input.
For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html).
---
Index of all JGuang resources: https://jiguang132.com/llms.txt