# Autocomplete

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

Source: [autocomplete.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/autocomplete.tsx)

```tsx
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 registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/autocomplete
```

## Usage

```tsx
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](https://ui.jarv.is/components/combobox.md). For several
values, use a [Tag Input](https://ui.jarv.is/components/tag-input.md), which takes the same suggestions.

## Composition

- `Autocomplete`
  - `AutocompleteInput`
  - `AutocompleteContent`
    - `AutocompleteStatus`
    - `AutocompleteEmpty`
    - `AutocompleteList`
      - `AutocompleteItem`
      - `AutocompleteGroup`
        - `AutocompleteLabel`
        - `AutocompleteCollection`
        - `AutocompleteSeparator`

## Examples

### With a label

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

```tsx
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.

```tsx
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:

```tsx
<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.

```tsx
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.

```tsx
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.

```tsx
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:

```bash
npx shadcn@latest add @jarvis/use-suggestions
```

## Props

`AutocompleteInput` is an [Input Group](https://ui.jarv.is/components/input-group.md) with optional clear and open
buttons. `AutocompleteContent` takes `side`, `sideOffset`, `align`, `alignOffset` and `anchor`.

| Part | Extends |
| --- | --- |
| `Autocomplete` | [`Autocomplete.Root`](https://base-ui.com/react/components/autocomplete#root) |
| `AutocompleteInput` | [`Autocomplete.Input`](https://base-ui.com/react/components/autocomplete#input) |
| `AutocompleteContent` | [`Autocomplete.Popup`](https://base-ui.com/react/components/autocomplete#popup) |
| `AutocompleteList` | [`Autocomplete.List`](https://base-ui.com/react/components/autocomplete#list) |
| `AutocompleteItem` | [`Autocomplete.Item`](https://base-ui.com/react/components/autocomplete#item) |
| `AutocompleteGroup` | [`Autocomplete.Group`](https://base-ui.com/react/components/autocomplete#group) |
| `AutocompleteLabel` | [`Autocomplete.GroupLabel`](https://base-ui.com/react/components/autocomplete#grouplabel) |
| `AutocompleteCollection` | [`Autocomplete.Collection`](https://base-ui.com/react/components/autocomplete#collection) |
| `AutocompleteSeparator` | [`Autocomplete.Separator`](https://base-ui.com/react/components/autocomplete#separator) |
| `AutocompleteEmpty` | [`Autocomplete.Empty`](https://base-ui.com/react/components/autocomplete#empty) |
| `AutocompleteStatus` | [`Autocomplete.Status`](https://base-ui.com/react/components/autocomplete#status) |

The tables leave out `className`, `style` and `render`. Parts built on Base UI take them as its [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides describe.

### Autocomplete

| Prop                    | Type                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?`             | `React.ReactNode`                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `name?`                 | `string`                                                                                                       | Identifies the field when a form is submitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `id?`                   | `string`                                                                                                       | The id of the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `required?`             | `boolean`                                                                                                      | Whether the user must choose a value before submitting a form. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `readOnly?`             | `boolean`                                                                                                      | Whether the user should be unable to choose a different option from the popup. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `disabled?`             | `boolean`                                                                                                      | Whether the component should ignore user interaction. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `defaultOpen?`          | `boolean`                                                                                                      | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `open?`                 | `boolean`                                                                                                      | Whether the popup is currently open. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `onOpenChangeComplete?` | `((open: boolean) => void)`                                                                                    | Event handler called after any animations complete when the popup is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `loopFocus?`            | `boolean`                                                                                                      | 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 <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input. The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>. Default: `true`                                       |
| `inputRef?`             | `React.Ref<HTMLInputElement>`                                                                                  | A ref to the hidden input element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `grid?`                 | `boolean`                                                                                                      | Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `virtualized?`          | `boolean`                                                                                                      | Whether the items are being externally virtualized. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `modal?`                | `boolean`                                                                                                      | 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. Default: `false`                                                                                                                                                                                           |
| `limit?`                | `number`                                                                                                       | The maximum number of items to display in the list. Default: `-1`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `locale?`               | `Intl.LocalesArgument`                                                                                         | The locale to use for string comparison. Defaults to the user's runtime locale.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `form?`                 | `string`                                                                                                       | Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `items?`                | `readonly unknown[] \| readonly Group<unknown>[]`                                                              | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `filter?`               | `((item: unknown, query: string, itemToString?: ((item: unknown) => string) \| undefined) => boolean) \| null` | Filter function used to match items against the input query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `mode?`                 | `"both" \| "inline" \| "list" \| "none"`                                                                       | 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. Default: `"list"` |
| `inline?`               | `boolean`                                                                                                      | 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>` Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `autoHighlight?`        | `"always" \| boolean`                                                                                          | 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. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `keepHighlight?`        | `boolean`                                                                                                      | Whether the highlighted item should be preserved when the pointer leaves the list. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `highlightItemOnHover?` | `boolean`                                                                                                      | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. Default: `true`                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `submitOnItemClick?`    | `boolean`                                                                                                      | Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form. Useful when the autocomplete is used as a single-field form search input. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                           |
| `itemToStringValue?`    | `((itemValue: unknown) => string)`                                                                             | 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.                                                                                                                                                                                                                                                                                                                                     |
| `actionsRef?`           | `React.RefObject<AutocompleteRootActions \| null>`                                                             | 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.                                                                                                                                                                                                                                                              |
| `onOpenChange?`         | `((open: boolean, eventDetails: AutocompleteRootOpenChangeEventDetails) => void)`                              | Event handler called when the popup is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `onItemHighlighted?`    | `((highlightedValue: unknown, eventDetails: AutocompleteRootHighlightEventDetails) => void)`                   | 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.                                                                 |
| `openOnInputClick?`     | `boolean`                                                                                                      | Whether the popup opens when clicking the input. Default: `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `value?`                | `string`                                                                                                       | The text in the input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `defaultValue?`         | `string`                                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `onValueChange?`        | `((value: string, details: Autocomplete.Root.ChangeEventDetails) => void)`                                     | Called as the text changes, including when a suggestion fills it in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `loadItems?`            | `((query: string, options: { signal: AbortSignal; }) => Promise<unknown[]>)`                                   | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `loadDeps?`             | `React.DependencyList`                                                                                         | What `loadItems` reads besides the text, such as a selected category. Suggestions load again when any of them changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `loadDelay?`            | `number`                                                                                                       | How long to wait after people stop typing before loading suggestions, in milliseconds. Default: `300`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

### AutocompleteInput

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

### AutocompleteContent

| Prop            | Type                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialFocus?` | `boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)`  | 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.                                                                                                                                                                                                                                        |
| `finalFocus?`   | `boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)` | 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.                                                                                                                                                                                                                                  |
| `anchor?`       | `Element \| React.RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`          | An element to position the popup against. By default, the popup will be positioned against the trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `side?`         | `"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"`                                                    | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. Default: `"bottom"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sideOffset?`   | `number \| OffsetFunction`                                                                                                    | 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. Default: `4` |
| `align?`        | `"center" \| "end" \| "start"`                                                                                                | How to align the popup relative to the specified side. Default: `"start"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `alignOffset?`  | `number \| OffsetFunction`                                                                                                    | 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. Default: `0`  |

### AutocompleteList

| Prop        | Type                                                                 | Description |
| ----------- | -------------------------------------------------------------------- | ----------- |
| `children?` | `((item: any, index: number) => React.ReactNode) \| React.ReactNode` |             |

### AutocompleteItem

| Prop            | Type                                                                           | Description                                                                                                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?`     | `React.ReactNode`                                                              |                                                                                                                                                                                                                                     |
| `onClick?`      | `((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | 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. |
| `index?`        | `number`                                                                       | The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.                                                                                      |
| `value?`        | `any`                                                                          | A unique value that identifies this item. Default: `null`                                                                                                                                                                           |
| `disabled?`     | `boolean`                                                                      | Whether the component should ignore user interaction. Default: `false`                                                                                                                                                              |
| `nativeButton?` | `boolean`                                                                      | 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. Default: `false`                                                       |

### AutocompleteGroup

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

### AutocompleteCollection

| Prop       | Type                                            | Description |
| ---------- | ----------------------------------------------- | ----------- |
| `children` | `(item: any, index: number) => React.ReactNode` |             |

### AutocompleteSeparator

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

### AutocompleteStatus

| Prop        | Type                                                                                     | Description                                                                                                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?` | `((state: { loading: boolean; error: boolean; }) => React.ReactNode) \| React.ReactNode` | 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. |