# Autocomplete

> A text input with suggestions that optionally complete your typing

Status: stable. Added in Components 2.0.0. Updated in Components 2.16.0, 20 Oct 2026.

A text input with suggestions that optionally complete your typing.

## Import

```tsx
import { Autocomplete } from '@oztix/roadie-components/autocomplete'
```

## Examples

### Default

```tsx
function AutocompleteDefault() {
  const cities = [
    'Brisbane',
    'Sydney',
    'Melbourne',
    'Perth',
    'Adelaide',
    'Hobart',
    'Darwin',
    'Canberra',
    'Gold Coast',
    'Newcastle',
  ]

  return (
    <Autocomplete items={cities}>
      <Autocomplete.InputGroup>
        <Autocomplete.Input placeholder='Type a city...' />
      </Autocomplete.InputGroup>
      <Autocomplete.Portal>
        <Autocomplete.Positioner>
          <Autocomplete.Popup>
            <Autocomplete.List>
              {(city) => (
                <Autocomplete.Item key={city} value={city}>
                  {city}
                </Autocomplete.Item>
              )}
            </Autocomplete.List>
            <Autocomplete.Empty>No cities found</Autocomplete.Empty>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete>
  )
}
```

### Emphasis

```tsx
<Autocomplete>
  <Autocomplete.InputGroup emphasis='normal'>
    <Autocomplete.Input placeholder='Normal emphasis' />
  </Autocomplete.InputGroup>
</Autocomplete>
<Autocomplete>
  <Autocomplete.InputGroup emphasis='subtle'>
    <Autocomplete.Input placeholder='Subtle emphasis' />
  </Autocomplete.InputGroup>
</Autocomplete>
```

### Sizes

```tsx
<Autocomplete>
  <Autocomplete.InputGroup size='sm'>
    <Autocomplete.Input placeholder='Small' />
  </Autocomplete.InputGroup>
</Autocomplete>
<Autocomplete>
  <Autocomplete.InputGroup size='md'>
    <Autocomplete.Input placeholder='Medium (default)' />
  </Autocomplete.InputGroup>
</Autocomplete>
<Autocomplete>
  <Autocomplete.InputGroup size='lg'>
    <Autocomplete.Input placeholder='Large' />
  </Autocomplete.InputGroup>
</Autocomplete>
```

### States

```tsx
{/* Default */}
<Autocomplete>
  <Autocomplete.InputGroup>
    <Autocomplete.Input placeholder='Type here...' />
  </Autocomplete.InputGroup>
</Autocomplete>
{/* Disabled */}
<Autocomplete disabled>
  <Autocomplete.InputGroup>
    <Autocomplete.Input placeholder='Type here...' />
  </Autocomplete.InputGroup>
</Autocomplete>
```

### Composition

#### With Field

Wrap Autocomplete in [Field](https://ticketsolutionsptyltd.github.io/roadie/components/field.md) for consistent layout, labels,
and error handling. Field.Label's `htmlFor` wires directly to the Autocomplete
input: clicking the label focuses the text field.

```tsx
function AutocompleteWithField() {
  const cities = [
    'Brisbane',
    'Sydney',
    'Melbourne',
    'Perth',
    'Adelaide',
    'Hobart',
    'Darwin',
    'Canberra',
  ]

  return (
    <Field>
      <Field.Label>City</Field.Label>
      <Autocomplete items={cities}>
        <Autocomplete.InputGroup>
          <Autocomplete.Input placeholder='Type a city...' />
          <Autocomplete.Clear />
        </Autocomplete.InputGroup>
        <Autocomplete.Portal>
          <Autocomplete.Positioner>
            <Autocomplete.Popup>
              <Autocomplete.List>
                {(city) => (
                  <Autocomplete.Item key={city} value={city}>
                    {city}
                  </Autocomplete.Item>
                )}
              </Autocomplete.List>
              <Autocomplete.Empty>No cities found</Autocomplete.Empty>
            </Autocomplete.Popup>
          </Autocomplete.Positioner>
        </Autocomplete.Portal>
      </Autocomplete>
    </Field>
  )
}
```

#### With trigger

```tsx
function AutocompleteWithTrigger() {
  const cities = [
    'Brisbane',
    'Sydney',
    'Melbourne',
    'Perth',
    'Adelaide',
    'Hobart',
  ]

  return (
    <Autocomplete items={cities}>
      <Autocomplete.InputGroup>
        <Autocomplete.Input placeholder='Type a city...' />
        <Autocomplete.Clear />
        <Autocomplete.Trigger />
      </Autocomplete.InputGroup>
      <Autocomplete.Portal>
        <Autocomplete.Positioner>
          <Autocomplete.Popup>
            <Autocomplete.List>
              {(city) => (
                <Autocomplete.Item key={city} value={city}>
                  {city}
                </Autocomplete.Item>
              )}
            </Autocomplete.List>
            <Autocomplete.Empty>No cities found</Autocomplete.Empty>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete>
  )
}
```

#### With groups

```tsx
function AutocompleteWithGroups() {
  const groups = [
    {
      value: 'New South Wales',
      items: ['Sydney', 'Newcastle', 'Wollongong', 'Central Coast'],
    },
    {
      value: 'Queensland',
      items: ['Brisbane', 'Gold Coast', 'Sunshine Coast', 'Cairns'],
    },
  ]

  return (
    <Autocomplete items={groups}>
      <Autocomplete.InputGroup>
        <Autocomplete.Input placeholder='Search by state...' />
      </Autocomplete.InputGroup>
      <Autocomplete.Portal>
        <Autocomplete.Positioner>
          <Autocomplete.Popup>
            <Autocomplete.List>
              {(group) => (
                <Autocomplete.Group key={group.value} items={group.items}>
                  <Autocomplete.GroupLabel>{group.value}</Autocomplete.GroupLabel>
                  <Autocomplete.Collection>
                    {(city) => (
                      <Autocomplete.Item key={city} value={city}>
                        {city}
                      </Autocomplete.Item>
                    )}
                  </Autocomplete.Collection>
                </Autocomplete.Group>
              )}
            </Autocomplete.List>
            <Autocomplete.Empty>No cities found</Autocomplete.Empty>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete>
  )
}
```

#### With rich items

Use custom markup inside `Autocomplete.Item` to show metadata like venue, date,
or an avatar alongside the primary label. Pass the item itself as `value`, and
use `itemToStringValue` to control what text appears in the input when an item
is selected, which includes the metadata so the user sees full context.

```tsx
function AutocompleteRichItems() {
  const events = [
    { name: 'Nectarine Hoedown', venue: 'Kazoo Hollow Room, Fortitude Valley', date: '17 Apr 2026, 7pm' },
    { name: 'Marzipan Thunderclap', venue: 'Wobbly Teacup Room, Thornbury', date: '17 Apr 2026, 7pm' },
    { name: 'Uncle Meteor and the Midnight Spoon Orchestra Live', venue: 'Opal Harpoon Room, Fitzroy', date: '26 Jul 2026, 7pm' },
    { name: 'Ironbark Satellite Tour', venue: 'Wobbly Teacup Room, Thornbury', date: '18 Apr 2026, 2pm' },
    { name: 'Ochre Kite Weekender 2026', venue: 'Lighthouse Fig Lawn, Crawley', date: '19 Apr 2026, 11am' },
    { name: 'Apricot Cyclone Fest', venue: 'Clockwork Wattle Brewery, North Fremantle', date: '11 Apr 2026, 3pm' },
  ]

  return (
    <Autocomplete
      items={events}
      itemToStringValue={(event) =>
        `${event.name} · ${event.venue} · ${event.date}`
      }
    >
      <Autocomplete.InputGroup>
        <Autocomplete.Input placeholder='Search events...' />
        <Autocomplete.Clear />
      </Autocomplete.InputGroup>
      <Autocomplete.Portal>
        <Autocomplete.Positioner>
          <Autocomplete.Popup>
            <Autocomplete.List>
              {(event) => (
                <Autocomplete.Item key={event.name} value={event}>
                  <div className='grid gap-0.5 min-w-0'>
                    <span className='truncate font-medium'>{event.name}</span>
                    <span className='truncate text-xs text-subtle'>
                      {event.venue} · {event.date}
                    </span>
                  </div>
                </Autocomplete.Item>
              )}
            </Autocomplete.List>
            <Autocomplete.Empty>No events found</Autocomplete.Empty>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete>
  )
}
```

## Guidelines

### When to use Autocomplete

Use Autocomplete when the user is typing **free text** and suggestions help
speed things up, but the typed value is always valid, even if it doesn't match
any suggestion.

- Address fields
- Search bars
- Tag input where custom values are allowed
- Any text field where suggestions are helpful but not required

### When to use Combobox or Select instead

If the user **must pick from the list**, use
[Combobox](https://ticketsolutionsptyltd.github.io/roadie/components/combobox.md). If the list is short and fixed, use
[Select](https://ticketsolutionsptyltd.github.io/roadie/components/select.md).

| Question                 | Select          | Combobox        | Autocomplete             |
| ------------------------ | --------------- | --------------- | ------------------------ |
| User types to filter?    | No              | Yes             | Yes                      |
| Must pick from the list? | Yes             | Yes             | No, typed value is valid |
| Options from an API?     | No              | Yes             | Yes                      |
| Custom/free-text value?  | No              | No              | Yes                      |
| Primary interaction      | Browse and pick | Search and pick | Type with suggestions    |
| Typical list size        | 2-15 items      | 10-500+ items   | Any                      |

### Filtering

Pass the `items` prop to `Autocomplete` root for built-in client-side filtering.
Use `Autocomplete.List` with a render function child to template each filtered
item:

```tsx
<Autocomplete items={cities}>
  ...
  <Autocomplete.List>
    {(city) => <Autocomplete.Item value={city}>{city}</Autocomplete.Item>}
  </Autocomplete.List>
  <Autocomplete.Empty>No results</Autocomplete.Empty>
</Autocomplete>
```

`Autocomplete.Empty` only renders when the filtered list is empty. It requires
the `items` prop on root.

The closest matches come first, so Enter takes the likeliest suggestion. An
exact match leads, then labels that start with the text, then labels with a
word that starts with it, then labels that contain it anywhere. Matches of the
same kind keep the order of `items`, and grouped items are ranked within their
group. Case and accents don't count, as in the filter.

Typing "Sydney" over `['North Sydney', 'Sydney']` lists Sydney first, so Enter
takes it. The order follows the value, whether typed or set in code, and with
no value `items` keep your order. With `limit` on a flat list, ranking comes
first, so the closest matches are the ones kept. Grouped items fill the limit
group by group, in your group order.

Roadie ranks only with its default filter, in `list` and `both` mode. Pass your
own `filter` or `filteredItems` to set the order yourself.

### Async loading

For server-side search, update the `items` prop as results arrive, and pass
`filter={null}` so the server's matches keep their order. Use
`Autocomplete.Status` to announce state changes to screen readers:

```tsx
<Autocomplete
  items={results}
  filter={null}
  onValueChange={(value) => fetchResults(value)}
>
  ...
  <Autocomplete.Status>{isLoading ? 'Loading...' : `${results.length} results`}</Autocomplete.Status>
</Autocomplete>
```

### Mode

The `mode` prop controls how filtering and inline autocompletion behave:

- **`list`** (default): items are filtered as you type. The input value stays
  as typed.
- **`both`**: items are filtered and the input temporarily shows the
  highlighted item's value (inline autocompletion).
- **`inline`**: items are **not** filtered. The input temporarily shows the
  highlighted item's value.
- **`none`**: items are static and the input value doesn't change based on
  highlighting.

In `both` and `inline` mode the first suggestion isn't highlighted for you,
since a highlight there would replace what the user typed.

### Keyboard behaviour

- Typing filters the list in real time and puts the closest matches first.
- Typing highlights the first suggestion, including suggestions that arrive
  later, so typing then pressing **Enter** takes it. Opening the list without
  typing highlights nothing new.
- **Arrow keys** move through the list. Once typing has highlighted the first
  suggestion, they move on from it and wrap at either end.
- **Enter** takes the highlighted suggestion. With nothing highlighted it
  keeps the typed text and submits the form. To keep text that matches a
  suggestion, press **Escape** to close the list, then **Enter**.
- **Escape** closes the popup.
- Set `autoHighlight={false}` to highlight only what the user moves to, as a
  search field that should always search the typed text needs.
  `autoHighlight='always'` also highlights the first suggestion with no text.

## Accessibility

- Wrap in `Field` and use `Field.Label` to name the input, which provides automatic `htmlFor` wiring.
- The input points `aria-activedescendant` at the highlighted suggestion, so
  screen readers read the first suggestion as the list filters.
- `Autocomplete.Empty` announces "no results" to screen readers automatically.
- `Autocomplete.Status` is a live region, use it for async status like loading
  or result counts.
- The input value is always valid, so screen readers don't need to announce
  selection errors.

## Hooks

### useFilteredItems

```tsx
function useFilteredItems<T>(): T[]
```

Returns the currently filtered `items`, read from inside an `Autocomplete`
tree. Treat the result as read-only: it's internal state and may be a shared
frozen array. Reach for it when a custom child needs to know what's actually
showing, such as a result count outside `Autocomplete.Status`.

## API reference

### Autocomplete

```tsx
import { Autocomplete } from '@oztix/roadie-components/autocomplete'
```

- `defaultValue`: `string | number | readonly string[]`. The uncontrolled input value of the autocomplete when it's initially rendered. To render a controlled autocomplete, use the `value` prop instead.
- `form`: `string`. Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form.
- `filter`: `((item: unknown, query: string, itemToString?: ((item: unknown) => string)) => boolean) | null`. Filter function used to match items against the input query.
- `disabled`: `boolean`. Defaults to `false`. Whether the component should ignore user interaction.
- `name`: `string`. Identifies the field when a form is submitted.
- `value`: `string | number | readonly string[]`. The input value of the autocomplete. Use when controlled.
- `id`: `string`. The id of the component.
- `grid`: `boolean`. Defaults to `false`. Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
- `inline`: `boolean`. Defaults to `false`. 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>`
- `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.
- `readOnly`: `boolean`. Defaults to `false`. Whether the user should be unable to choose a different option from the popup.
- `required`: `boolean`. Defaults to `false`. Whether the user must choose a value before submitting a form.
- `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.
- `keepHighlight`: `boolean`. Defaults to `false`. Whether the highlighted item should be preserved when the pointer leaves the list.
- `highlightItemOnHover`: `boolean`. Defaults to `true`. Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
- `actionsRef`: `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.
- `openOnInputClick`: `boolean`. Defaults to `false`. Whether the popup opens when clicking the input.
- `filteredItems`: `readonly unknown[] | readonly Group<unknown>[]`. Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. Nullish entries are not supported, as in `items`. Use when you want to control filtering logic externally with the `useFilter()` hook.
- `defaultOpen`: `boolean`. Defaults to `false`. Whether the popup is initially open. To render a controlled popup, use the `open` prop instead.
- `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`. Defaults to `true`. 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>.
- `onItemHighlighted`: `((highlightedValue: unknown, eventDetails: HighlightEventDetails) => 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.
- `inputRef`: `Ref<HTMLInputElement>`. A ref to the hidden input element.
- `virtualized`: `boolean`. Defaults to `false`. Whether the items are being externally virtualized.
- `modal`: `boolean`. Defaults to `false`. 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.
- `limit`: `number`. Defaults to `-1`. The maximum number of items to display in the list.
- `locale`: `LocalesArgument`. The locale to use for string comparison. Defaults to the user's runtime locale.
- `submitOnItemClick`: `boolean`. Defaults to `false`. 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.
- `mode`: `"none" | "list" | "inline" | "both"`. Defaults to `'list'`. 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.
- `onValueChange`: `((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void)`. Event handler called when the input value of the autocomplete changes.
- `autoHighlight`: `boolean | "always"`. Whether the first suggestion is highlighted, so Enter takes it. - `true`: once the user types, including suggestions that arrive later. Opening the list without typing highlights nothing, so Enter submits. - `'always'`: whenever suggestions show, even with no text. - `false`: only an item moved to with the arrows. Defaults to `true`, or `false` in `both` and `inline` mode, where a highlight fills the input.

### Autocomplete.Clear

- `disabled`: `boolean`. Defaults to `false`. Whether the component should ignore user interaction.
- `keepMounted`: `boolean`. Defaults to `false`. Whether the component should remain mounted in the DOM when not visible.
- `nativeButton`: `boolean`. Defaults to `true`. Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
- `className`: `string | ((state: ComboboxClearState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Collection

No props beyond the standard HTML attributes.

### Autocomplete.Empty

- `className`: `string | ((state: ComboboxEmptyState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Group

- `items`: `readonly any[]`. Items to be rendered within this group. When provided, child `Collection` components will use these items.
- `className`: `string | ((state: ComboboxGroupState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.GroupLabel

- `className`: `string | ((state: ComboboxGroupLabelState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Input

- `disabled`: `boolean`. Defaults to `false`. Whether the component should ignore user interaction.
- `className`: `string | ((state: ComboboxInputState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.InputGroup

- `className`: `string | ((state: AutocompleteInputGroupState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.
- `size`: `"sm" | "md" | "lg" | null`.
- `intent`: `"neutral" | "brand" | "brand-secondary" | "brand-blue" | "brand-orange" | "brand-purple" | "accent" | "danger" | "success" | "warning" | "info" | null`.
- `emphasis`: `"normal" | "subtle" | null`.

### Autocomplete.Item

- `onClick`: `((event: BaseUIEvent<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`. Defaults to `null`. A unique value that identifies this item.
- `disabled`: `boolean`. Defaults to `false`. Whether the component should ignore user interaction.
- `nativeButton`: `boolean`. Defaults to `true`. Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
- `className`: `string | ((state: AutocompleteItemState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.List

- `className`: `string | ((state: ComboboxListState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Popup

- `initialFocus`: `boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | 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 | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | 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.
- `className`: `string | ((state: ComboboxPopupState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Portal

- `keepMounted`: `boolean`. Defaults to `false`. Whether to keep the portal mounted in the DOM while the popup is hidden.
- `container`: `HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null`. A parent element to render the portal element into.
- `className`: `string | ((state: ComboboxPortalState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Positioner

- `anchor`: `Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null`. An element to position the popup against. By default, the popup will be positioned against the trigger.
- `positionMethod`: `"absolute" | "fixed"`. Defaults to `'absolute'`. Determines which CSS `position` property to use.
- `side`: `"top" | "bottom" | "left" | "right" | "inline-end" | "inline-start"`. Defaults to `'bottom'`. Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
- `sideOffset`: `number | OffsetFunction`. Defaults to `0`. 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. @example `jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> `
- `align`: `"center" | "start" | "end"`. Defaults to `'center'`. How to align the popup relative to the specified side.
- `alignOffset`: `number | OffsetFunction`. Defaults to `0`. 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. @example `jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> `
- `collisionBoundary`: `Boundary`. Defaults to `'clipping-ancestors'`. An element or a rectangle that delimits the area that the popup is confined to.
- `collisionPadding`: `Padding`. Defaults to `5`. Additional space to maintain from the edge of the collision boundary.
- `sticky`: `boolean`. Defaults to `false`. Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
- `arrowPadding`: `number`. Defaults to `5`. Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
- `disableAnchorTracking`: `boolean`. Defaults to `false`. Whether to disable the popup from tracking any layout shift of its positioning anchor.
- `collisionAvoidance`: `CollisionAvoidance`. Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`. @example `jsx <Positioner collisionAvoidance={{ side: 'shift', align: 'shift', fallbackAxisSide: 'none', }} /> `
- `className`: `string | ((state: ComboboxPositionerState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Status

- `className`: `string | ((state: ComboboxStatusState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Trigger

- `disabled`: `boolean`. Defaults to `false`. Whether the component should ignore user interaction.
- `nativeButton`: `boolean`. Defaults to `true`. Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
- `className`: `string | ((state: AutocompleteTriggerState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Autocomplete.Value

No props beyond the standard HTML attributes.

Docs updated 19 Oct 2026.