Sections

Utilities

Autocomplete

Displays a searchable list of options to choose from.

Installation


pnpm dlx shadcn@latest add https://shark.vini.one/r/autocomplete.json

Usage


import { useFilter, useListCollection } from "@ark-ui/react";
import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";


const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Apple", value: "apple", group: "Fruits" },
    { label: "Banana", value: "banana", group: "Fruits" },
  ],
  filter: contains,
  groupBy: (item) => item.group, // optional
});
 
<Autocomplete
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>
  <AutocompleteInput placeholder="Select an option" />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteList>
      {collection.group().map(([group, items]) => (
        <AutocompleteGroup heading={group} key={group}>
          {items.map((item) => (
            <AutocompleteItem item={item} key={item.value}>
              {item.label}
            </AutocompleteItem>
          ))}
        </AutocompleteGroup>
      ))}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

Controlled

Control the selected value with value and onValueChange props. Use inputValue and onInputValueChange for controlling the input text.

Selected: banana

Sizes

Small

Medium

Large

State

Invalid

Disabled

Examples

Inline autocomplete

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

Group

With Field

Use Autocomplete with <Field /> components to style with the field components.

With clear button

Pass showClear to <AutocompleteInput /> to show a clear button.

With trigger

Pass showTrigger to <AutocompleteInput /> to show the dropdown trigger button.

With start icon

API Reference

Autocomplete

Combines input, dropdown trigger, and list into a searchable select.

Prop	Type	Default
`collection`	`ListCollection<T>`	required
`value`	`string \| string[]`	-
`defaultValue`	`string \| string[]`	-
`onValueChange`	`(details: ValueChangeDetails<T>) => void`	-
`onInputValueChange`	`(details: InputValueChangeDetails) => void`	-
`disabled`	`boolean`	-
`openOnClick`	`boolean`	`true`
`lazyMount`	`boolean`	`true`
`unmountOnExit`	`boolean`	`true`
`className`	`string`	-

AutocompleteInput

Text input with optional dropdown trigger and clear button. Supports size variants.

Prop	Type	Default
`size`	`"sm" \| "md" \| "lg"`	`"md"`
`showTrigger`	`boolean`	`false`
`showClear`	`boolean`	`false`
`disabled`	`boolean`	-
`className`	`string`	-
`asChild`	`boolean`	-

AutocompleteContent

Dropdown that displays filtered suggestions. Portaled to overlay other content.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

AutocompleteItem

Single selectable option in the suggestion list. Pass item from the collection.

Prop	Type	Default
`item`	`T`	required
`className`	`string`	-
`asChild`	`boolean`	-

AutocompleteGroup

Groups related items. Use with groupBy on the collection.

Prop	Type	Default
`heading`	`string \| ReactNode`	-
`className`	`string`	-
`asChild`	`boolean`	-

AutocompleteGroupLabel

Heading for a group of items. Use inside AutocompleteGroup.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

AutocompleteEmpty

Content when no items match the filter. Default: "No results found."

Prop	Type	Default
`className`	`string`	-
`children`	`ReactNode`	-

AutocompleteControl / AutocompleteTrigger / AutocompleteClear

Optional building blocks for custom layouts. Use AutocompleteInput for the standard layout.

For a complete list of props, see the Ark UI documentation.