Autocomplete

A text field that suggests values as people type, and takes any text.

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const departments = [
  "Customer Support",
  "Design",
  "Engineering",
  "Finance",
  "Legal",
  "Marketing",
  "Operations",
  "People",
  "Product",
  "Sales",
];

export default function AutocompleteBasic() {
  return (
    <Autocomplete items={departments}>
      <AutocompleteInput
        placeholder="e.g. Engineering"
        aria-label="Department"
        className="w-full max-w-xs"
      />
      <AutocompleteContent>
        <AutocompleteList>
          {(item: string) => (
            <AutocompleteItem key={item} value={item}>
              {item}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}

Installation

Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
Add autocomplete
pnpm dlx shadcn@latest add @jarvis/autocomplete

Usage

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const cities = ["Berlin", "Dublin", "Lisbon", "London", "Stockholm"];

export function CityField() {
  return (
    <Autocomplete items={cities}>
      <AutocompleteInput placeholder="e.g. Lisbon" aria-label="City" />
      <AutocompleteContent>
        <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
        <AutocompleteList>
          {(item: string) => (
            <AutocompleteItem key={item} value={item}>
              {item}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}

Pass the suggestions as items and render each one inside AutocompleteList. The list opens as people type, or on the down arrow, and shows the suggestions that contain what's typed. Picking one fills in the input, but the value is always the text, so people can type something that isn't suggested. The list closes when nothing matches, unless it has an AutocompleteEmpty to say so. Label the input with aria-label or a FieldLabel.

When the value has to be one of the options, use a Combobox. For several values, use a Tag Input, which takes the same suggestions.

Composition

Autocomplete
- AutocompleteInput
- AutocompleteContent

Examples

With a label

Put it in a Field with a FieldLabel, which labels the input.

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";

const titles = [
  "Account Executive",
  "Data Analyst",
  "Designer",
  "Engineering Manager",
  "Product Manager",
  "Recruiter",
  "Software Engineer",
  "Support Specialist",
];

export default function AutocompleteWithField() {
  return (
    <Field className="max-w-xs">
      <FieldLabel>Job title</FieldLabel>
      <Autocomplete items={titles}>
        <AutocompleteInput placeholder="e.g. Designer" />
        <AutocompleteContent>
          <AutocompleteEmpty>No suggestions. Your title works too.</AutocompleteEmpty>
          <AutocompleteList>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
      <FieldDescription>Pick a suggestion or write your own.</FieldDescription>
    </Field>
  );
}

Async

To load suggestions from somewhere else, such as a search endpoint, pass loadItems in place of items. It's called with the typed text once people stop typing for loadDelay milliseconds, 300 by default, and with an AbortSignal that aborts when they type again, so pass it on to fetch. Its results are shown as given. An AutocompleteStatus shows a spinner while they load and a message if loading fails, and screen readers announce both, then how many suggestions arrived. A failed search runs again once the text changes and comes back to it. Until new results arrive, the last ones stay in the list, dimmed. Here a stand-in for the endpoint answers after 600 milliseconds with the libraries that start with what's typed.

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompleteStatus,
} from "@/components/ui/autocomplete";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { searchLibraries } from "@/examples/data";

export default function AutocompleteAsync() {
  return (
    <Field className="max-w-xs">
      <FieldLabel>Library</FieldLabel>
      <Autocomplete loadItems={searchLibraries}>
        <AutocompleteInput placeholder="Search libraries" />
        <AutocompleteContent>
          <AutocompleteStatus />
          <AutocompleteEmpty>No libraries match.</AutocompleteEmpty>
          <AutocompleteList>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
      <FieldDescription>Suggestions load as you type, such as "re".</FieldDescription>
    </Field>
  );
}

With autoHighlight, which highlights the first suggestion as people type, Enter fills in a suggestion only when it's among the results for what's typed, never one left from an earlier search.

When loadItems reads something besides the text, such as a selected category, list it in loadDeps, and suggestions load again when it changes, the way an effect's dependencies work:

<Autocomplete
  loadItems={(query, options) => search(query, category, options)}
  loadDeps={[category]}
>

Groups

Pass groups as items, each with its own items, and render them with AutocompleteGroup and AutocompleteCollection. A group with no matches is left out. End each group with an AutocompleteSeparator, which hides itself in the last group shown.

import {
  Autocomplete,
  AutocompleteCollection,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteLabel,
  AutocompleteList,
  AutocompleteSeparator,
} from "@/components/ui/autocomplete";

const cities = [
  { value: "Americas", items: ["Chicago", "Mexico City", "New York", "São Paulo", "Toronto"] },
  { value: "Europe", items: ["Berlin", "Dublin", "Lisbon", "London", "Stockholm"] },
  { value: "Asia Pacific", items: ["Bengaluru", "Singapore", "Sydney", "Tokyo"] },
];

export default function AutocompleteGroups() {
  return (
    <Autocomplete items={cities}>
      <AutocompleteInput placeholder="e.g. Lisbon" aria-label="City" className="w-full max-w-xs" />
      <AutocompleteContent>
        <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
        <AutocompleteList>
          {(group: (typeof cities)[number]) => (
            <AutocompleteGroup key={group.value} items={group.items}>
              <AutocompleteLabel>{group.value}</AutocompleteLabel>
              <AutocompleteCollection>
                {(item: string) => (
                  <AutocompleteItem key={item} value={item}>
                    {item}
                  </AutocompleteItem>
                )}
              </AutocompleteCollection>
              <AutocompleteSeparator />
            </AutocompleteGroup>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}

Search

Put an InputGroupAddon in AutocompleteInput for an icon, and set showClear for a button that clears the text.

import { SearchIcon } from "lucide-react";

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";
import { InputGroupAddon } from "@/components/ui/input-group";

const recent = ["billing settings", "invoice export", "team roles", "API keys", "audit log"];

export default function AutocompleteSearch() {
  return (
    <Autocomplete items={recent}>
      <AutocompleteInput
        placeholder="Search settings"
        aria-label="Search settings"
        showClear
        className="w-full max-w-xs"
      >
        <InputGroupAddon>
          <SearchIcon />
        </InputGroupAddon>
      </AutocompleteInput>
      <AutocompleteContent>
        <AutocompleteList>
          {(item: string) => (
            <AutocompleteItem key={item} value={item}>
              <SearchIcon />
              {item}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}

Objects

For object items, itemToStringValue returns the text to match and fill in. showTrigger adds a button that opens the suggestions: all of them when nothing is typed, or the ones that match.

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { people, type Person } from "@/examples/data";

export default function AutocompleteObjects() {
  return (
    <Autocomplete items={people} itemToStringValue={(person: Person) => person.name}>
      <AutocompleteInput
        placeholder="Search people"
        aria-label="Person"
        showTrigger
        className="w-full max-w-xs"
      />
      <AutocompleteContent>
        <AutocompleteEmpty>No one matches.</AutocompleteEmpty>
        <AutocompleteList>
          {(person: Person) => (
            <AutocompleteItem key={person.value} value={person} className="h-auto py-1.5">
              <Avatar size="sm">
                <AvatarImage src={person.image} alt="" />
                <AvatarFallback>{person.initials}</AvatarFallback>
              </Avatar>
              <span className="flex min-w-0 flex-col">
                <span className="truncate">{person.name}</span>
                <span className="truncate text-2xs text-muted-foreground">{person.email}</span>
              </span>
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}

Your own suggestions

useSuggestions, the hook behind loadItems here and loadSuggestions in Tag Input, loads suggestions for any control. It takes the query and a load function, with deps, delay, and onLoad and onError callbacks, and returns the items for the query, loading and error. seen returns every suggestion loaded so far, one for each text when you pass itemToStringValue. Pass onItemHighlighted to a Base UI root's prop of the same name, and highlight tells why a suggestion is highlighted: people chosen it, it was highlighted for them (auto), or that happened among results being replaced (stale).

To add the hook on its own:

pnpm dlx shadcn@latest add @jarvis/use-suggestions

Props

AutocompleteInput is an Input Group with optional clear and open buttons. AutocompleteContent takes side, sideOffset, align, alignOffset and anchor.

Part	Extends
Autocomplete	Base UI's Autocomplete.Root
AutocompleteInput	Base UI's Autocomplete.Input
AutocompleteContent	Base UI's Autocomplete.Popup
AutocompleteList	Base UI's Autocomplete.List
AutocompleteItem	Base UI's Autocomplete.Item
AutocompleteGroup	Base UI's Autocomplete.Group
AutocompleteLabel	Base UI's Autocomplete.GroupLabel
AutocompleteCollection	Base UI's Autocomplete.Collection
AutocompleteSeparator	Base UI's Autocomplete.Separator
AutocompleteEmpty	Base UI's Autocomplete.Empty
AutocompleteStatus	Base UI's Autocomplete.Status

The tables leave out className, style and render. Parts built on Base UI take them as its styling and composition guides describe.

Autocomplete

Prop	Type	Default
`children`	`React.ReactNode`	—
`name` Identifies the field when a form is submitted.	`string`	—
`id` The id of the component.	`string`	—
`required` Whether the user must choose a value before submitting a form.	`boolean`	`false`
`readOnly` Whether the user should be unable to choose a different option from the popup.	`boolean`	`false`
`disabled` Whether the component should ignore user interaction.	`boolean`	`false`
`defaultOpen` Whether the popup is initially open. To render a controlled popup, use the `open` prop instead.	`boolean`	`false`
`open` Whether the popup is currently open. Use when controlled.	`boolean`	—
`onOpenChangeComplete` Event handler called after any animations complete when the popup is opened or closed.	`((open: boolean) => void)`	—
`loopFocus` Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing ArrowDown again from the input, or the last item can be reached by pressing ArrowUp from the input. The input is always included in the focus loop per ARIA Authoring Practices. When disabled, focus does not move when on the last element and the user presses ArrowDown, or when on the first element and the user presses ArrowUp.	`boolean`	`true`
`inputRef` A ref to the hidden input element.	`React.Ref<HTMLInputElement>`	—
`grid` Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.	`boolean`	`false`
`virtualized` Whether the items are being externally virtualized.	`boolean`	`false`
`modal` Determines if the popup enters a modal state when open. `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.	`boolean`	`false`
`limit` The maximum number of items to display in the list.	`number`	`-1`
`locale` The locale to use for string comparison. Defaults to the user's runtime locale.	`Intl.LocalesArgument`	—
`form` Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form.	`string`	—
`items` The items to be displayed in the list. Can be either a flat array of items or an array of groups with items. Nullish entries are not supported: remove them from the data before passing it.	`readonly unknown[] \| readonly Group<unknown>[]`	—
`filter` Filter function used to match items against the input query.	`((item: unknown, query: string, itemToString?: ((item: unknown) => string) \| undefined) => boolean) \| null`	—
`mode` Controls how the autocomplete behaves with respect to list filtering and inline autocompletion. `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item. `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion). `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion). `none`: items are static (not filtered), and the input value will not change based on the active item.	`"both" \| "inline" \| "list" \| "none"`	`"list"`
`inline` Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Autocomplete.Root inline open>`	`boolean`	`false`
`autoHighlight` Whether the first matching item is highlighted automatically. `true`: highlight after the user types and keep the highlight while the query changes. `'always'`: always highlight the first item.	`"always" \| boolean`	`false`
`keepHighlight` Whether the highlighted item should be preserved when the pointer leaves the list.	`boolean`	`false`
`highlightItemOnHover` Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.	`boolean`	`true`
`submitOnItemClick` Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or Enter key does not submit the owning form. Useful when the autocomplete is used as a single-field form search input.	`boolean`	`false`
`itemToStringValue` When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.	`((itemValue: unknown) => string)`	—
`actionsRef` A ref to imperative actions. `unmount`: Ends the closing phase of the autocomplete after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the autocomplete completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. `close`: Closes the autocomplete imperatively when called.	`React.RefObject<AutocompleteRootActions \| null>`	—
`onOpenChange` Event handler called when the popup is opened or closed.	`((open: boolean, eventDetails: AutocompleteRootOpenChangeEventDetails) => void)`	—
`onItemHighlighted` Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: `'keyboard'`: the highlight changed due to keyboard navigation. `'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent` rather than a `PointerEvent`. `'none'`: the highlight changed for another reason, such as typing, `autoHighlight`, the item list changing, or the popup opening or closing.	`((highlightedValue: unknown, eventDetails: AutocompleteRootHighlightEventDetails) => void)`	—
`openOnInputClick` Whether the popup opens when clicking the input.	`boolean`	`false`
`value` The text in the input.	`string`	—
`defaultValue`	`string`	—
`onValueChange` Called as the text changes, including when a suggestion fills it in.	`((value: string, details: Autocomplete.Root.ChangeEventDetails) => void)`	—
`loadItems` Loads the suggestions for the typed text, such as from a search endpoint, in place of `items`. It's called once people pause typing, with a signal that aborts when they type again, and its results are shown as given.	`((query: string, options: { signal: AbortSignal; }) => Promise<unknown[]>)`	—
`loadDeps` What `loadItems` reads besides the text, such as a selected category. Suggestions load again when any of them changes.	`React.DependencyList`	—
`loadDelay` How long to wait after people stop typing before loading suggestions, in milliseconds.	`number`	`300`

AutocompleteInput

Prop	Type	Default
`disabled` Whether the component should ignore user interaction.	`boolean`	`false`
`showTrigger` Whether to show a button that opens the suggestions, filtered by any text already typed.	`boolean`	`false`
`showClear` Whether to show a button that clears the text.	`boolean`	`false`
`size`	`"default" \| "lg"`	`"default"`

AutocompleteContent

Prop	Type	Default
`initialFocus` Determines the element to focus when the popup is opened. `false`: Do not move focus. `true`: Move focus based on the default behavior (first tabbable element or popup). `RefObject`: Move focus to the ref element. `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)`	—
`finalFocus` Determines the element to focus when the popup is closed. `false`: Do not move focus. `true`: Move focus based on the default behavior (trigger or previously focused element). `RefObject`: Move focus to the ref element. `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)`	—
`anchor` An element to position the popup against. By default, the popup will be positioned against the trigger.	`Element \| React.RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	—
`side` Which side of the anchor element to align the popup against. May automatically change to avoid collisions.	`"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"`	`"bottom"`
`sideOffset` Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. `data.side`: which side of the anchor element the positioner is aligned against. `data.align`: how the positioner is aligned relative to the specified side.	`number \| OffsetFunction`	`4`
`align` How to align the popup relative to the specified side.	`"center" \| "end" \| "start"`	`"start"`
`alignOffset` Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. `data.side`: which side of the anchor element the positioner is aligned against. `data.align`: how the positioner is aligned relative to the specified side.	`number \| OffsetFunction`	`0`

AutocompleteList

Prop	Type	Default
`children`	`((item: any, index: number) => React.ReactNode) \| React.ReactNode`	—

AutocompleteItem

Prop	Type	Default
`children`	`React.ReactNode`	—
`onClick` An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus.	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	—
`index` The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.	`number`	—
`value` A unique value that identifies this item.	`any`	`null`
`disabled` Whether the component should ignore user interaction.	`boolean`	`false`
`nativeButton` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.	`boolean`	`false`

AutocompleteGroup

Prop	Type	Default
`items` Items to be rendered within this group. When provided, child `Collection` components will use these items.	`readonly any[]`	—

AutocompleteCollection

Prop	Type	Default
`children`	`(item: any, index: number) => React.ReactNode`	—

AutocompleteSeparator

Prop	Type	Default
`orientation` The orientation of the separator.	`"horizontal" \| "vertical"`	`'horizontal'`

AutocompleteStatus

Prop	Type	Default
`children` What to show while suggestions load or after they fail to. Without it, a spinner with "Searching…", or "Couldn't load suggestions.", and once suggestions are shown, their count for screen readers.	`((state: { loading: boolean; error: boolean; }) => React.ReactNode) \| React.ReactNode`	—