Autocomplete
A searchable multi-select input that allows users to filter and pick multiple options from a list using checkboxes.
Examples
Default
Preview
Disabled
Preview
Invalid
Preview
With Helper Text
Preview
With Footer
Preview
API
Root
Contains all the parts of the autocomplete. Manages open/close state and the selected values.
| Property | Type | Default | Description |
|---|---|---|---|
| defaultValues | string[] | [] | The initial selected values when uncontrolled. |
| values | string[] | - | The controlled selected values. Use with onValuesChange. |
| onValuesChange | (values: string[]) => void | - | Event handler called when the selected values change. |
| open | boolean | - | The controlled open state of the dropdown. |
| onOpenChange | (open: boolean) => void | - | Event handler called when the open state changes. |
| disabled | boolean | false | When true, prevents the user from interacting with the autocomplete. |
| invalid | boolean | false | When true, enables error state styling for the trigger and helper text. |
Trigger
The button that toggles the dropdown. Always displays the placeholder text regardless of selection.
| Property | Type | Default | Description |
|---|---|---|---|
| placeholder | string | ”Select an option” | The text always displayed in the trigger button. |
| className | string | - | Additional CSS classes for the trigger button. |
Content
The dropdown panel that contains the search input and list of options.
| Property | Type | Default | Description |
|---|---|---|---|
| searchPlaceholder | string | ”Search…” | Placeholder text for the search input inside the dropdown. |
| emptyMessage | string | ”No results found.” | Message displayed when no items match the search query. |
| className | string | - | Additional CSS classes for the content container. |
Item
An individual selectable option inside the dropdown. Displays a checkbox that toggles on selection. The dropdown stays open after selecting an item.
| Property | Type | Default | Description |
|---|---|---|---|
| value | string | - | The unique identifier of the item, used for selection tracking. Can be an ID. Required. |
| name | string | - | Optional display name used for search/filtering. Useful when value is an opaque ID that wouldn’t match user input. When omitted, search matches against value and children text content. |
| disabled | boolean | false | When true, prevents the user from selecting the item. |
| className | string | - | Additional CSS classes for the item. |
Group
Used to group related items inside the content.
| Property | Type | Default | Description |
|---|---|---|---|
| heading | ReactNode | - | Optional heading label rendered above the group items. |
| className | string | - | Additional CSS classes for the group container. |
Text
Helper text displayed below the trigger. Automatically shows error styling when the root has invalid={true}.
| Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional CSS classes for the helper text. |
| children | ReactNode | - | The text content. Styled as error text (feedback-error-foreground) when invalid, otherwise normal color (gray-foreground). |
ContentFooter
Optional footer rendered at the bottom of the dropdown panel with Cancel and Done action buttons. Place it as a child of AutocompleteContent.
| Property | Type | Default | Description |
|---|---|---|---|
| cancelLabel | string | ”Cancel” | Label for the cancel button. |
| confirmLabel | string | ”Done” | Label for the confirm button. |
| onCancel | () => void | - | Callback fired when the cancel button is clicked. The dropdown closes automatically. |
| onConfirm | (values: string[]) => void | - | Callback fired when the confirm button is clicked. Receives the current selected values and closes the dropdown automatically. |
| className | string | - | Additional CSS classes for the footer container. |