# Combobox

> A searchable dropdown for filtering and selecting from a list of options

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

A searchable dropdown for filtering and selecting from a list of options.

## Import

```tsx
import { Combobox } from '@oztix/roadie-components/combobox'
```

## Examples

### Default

```tsx
function ComboboxDefault() {
  const bands = [
    'Powderfinger',
    'Custard',
    'Regurgitator',
    'The Go-Betweens',
    'Violent Soho',
    'DZ Deathrays',
    'Ball Park Music',
    'The Goon Sax',
    'Cub Sport',
    'The Jungle Giants',
  ]

  return (
    <Combobox items={bands}>
      <Combobox.InputGroup>
        <Combobox.Input placeholder='Search bands...' />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Portal>
        <Combobox.Positioner>
          <Combobox.Popup>
            <Combobox.List>
              {(band) => (
                <Combobox.Item key={band} value={band}>
                  {band}
                  <Combobox.ItemIndicator />
                </Combobox.Item>
              )}
            </Combobox.List>
            <Combobox.Empty>No bands found</Combobox.Empty>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox>
  )
}
```

### Emphasis

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

### Sizes

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

### States

```tsx
{/* Default */}
<Combobox>
  <Combobox.InputGroup>
    <Combobox.Input placeholder='Search...' />
    <Combobox.Trigger />
  </Combobox.InputGroup>
</Combobox>
{/* Disabled */}
<Combobox disabled>
  <Combobox.InputGroup>
    <Combobox.Input placeholder='Search...' />
    <Combobox.Trigger />
  </Combobox.InputGroup>
</Combobox>
```

### Composition

#### With Field

Wrap Combobox 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 Combobox input:
clicking the label focuses the search field.

```tsx
function ComboboxWithField() {
  const bands = [
    'Powderfinger',
    'Custard',
    'Regurgitator',
    'Violent Soho',
    'DZ Deathrays',
    'Ball Park Music',
  ]

  return (
    <Field required>
      <Field.Label showIndicator>Favourite band</Field.Label>
      <Combobox items={bands}>
        <Combobox.InputGroup>
          <Combobox.Input placeholder='Search bands...' />
          <Combobox.Clear />
          <Combobox.Trigger />
        </Combobox.InputGroup>
        <Combobox.Portal>
          <Combobox.Positioner>
            <Combobox.Popup>
              <Combobox.List>
                {(band) => (
                  <Combobox.Item key={band} value={band}>
                    {band}
                    <Combobox.ItemIndicator />
                  </Combobox.Item>
                )}
              </Combobox.List>
              <Combobox.Empty>No bands found</Combobox.Empty>
            </Combobox.Popup>
          </Combobox.Positioner>
        </Combobox.Portal>
      </Combobox>
    </Field>
  )
}
```

#### With groups

```tsx
function ComboboxWithGroups() {
  const groups = [
    {
      value: 'Brisbane',
      items: ['Powderfinger', 'Custard', 'Regurgitator', 'The Go-Betweens', 'The Saints'],
    },
    {
      value: 'Gold Coast',
      items: ['Violent Soho', 'DZ Deathrays', 'The Goon Sax', 'Cub Sport'],
    },
  ]

  return (
    <Combobox items={groups}>
      <Combobox.InputGroup>
        <Combobox.Input placeholder='Search by region...' />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Portal>
        <Combobox.Positioner>
          <Combobox.Popup>
            <Combobox.List>
              {(group) => (
                <Combobox.Group key={group.value} items={group.items}>
                  <Combobox.GroupLabel>{group.value}</Combobox.GroupLabel>
                  <Combobox.Collection>
                    {(band) => (
                      <Combobox.Item key={band} value={band}>
                        {band}
                        <Combobox.ItemIndicator />
                      </Combobox.Item>
                    )}
                  </Combobox.Collection>
                </Combobox.Group>
              )}
            </Combobox.List>
            <Combobox.Empty>No bands found</Combobox.Empty>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox>
  )
}
```

#### With rich items

Use custom markup inside `Combobox.Item` to show metadata like a subtitle or
secondary label alongside the primary text. Pass the item itself as `value`, and
use `itemToStringLabel` to set the text the input shows and filters on.

```tsx
function ComboboxRichItems() {
  const venues = [
    { name: 'Iguana Teapot Hall', location: 'Fortitude Valley, QLD' },
    { name: 'Clockwork Wattle Brewery', location: 'Newstead, QLD' },
    { name: 'Gooseberry Signal Warehouse', location: 'Fortitude Valley, QLD' },
    { name: 'Opal Harpoon Room', location: 'Fortitude Valley, QLD' },
    { name: 'Echidna Gaslight Theatre', location: 'Woolloongabba, QLD' },
    { name: 'Jumbuck Orchard Park', location: 'South Bank, QLD' },
    { name: 'Nimbus Thistle Hall', location: 'Fortitude Valley, QLD' },
    { name: 'Foxglove Tin Pavilion', location: 'Fortitude Valley, QLD' },
  ]

  return (
    <Combobox items={venues} itemToStringLabel={(venue) => venue.name}>
      <Combobox.InputGroup>
        <Combobox.Input placeholder='Search venues...' />
        <Combobox.Clear />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Portal>
        <Combobox.Positioner>
          <Combobox.Popup>
            <Combobox.List>
              {(venue) => (
                <Combobox.Item key={venue.name} value={venue}>
                  <div className='grid gap-0.5 min-w-0'>
                    <span className='truncate font-medium'>{venue.name}</span>
                    <span className='truncate text-xs text-subtle'>{venue.location}</span>
                  </div>
                  <Combobox.ItemIndicator />
                </Combobox.Item>
              )}
            </Combobox.List>
            <Combobox.Empty>No venues found</Combobox.Empty>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox>
  )
}
```

### Multiple selection

Set `multiple` to pick more than one value. `Combobox.Value` hands the current
values to a function; render a `Combobox.Chip` for each one inside
`Combobox.Chips`, with the input last. Put the text in `Combobox.ChipLabel` so a
long value truncates. The input group grows as the chips wrap. A chip with
focus shows as selected. Set `selected` on `Combobox.Chip` to show it selected
while focus stays in the input, as QueryField does while it edits a chip.

```tsx
function ComboboxMultiple() {
  const genres = [
    'Rock',
    'Indie',
    'Hip hop',
    'Electronic',
    'Jazz',
    'Folk',
    'Country',
    'Metal',
    'Punk',
    'Soul',
  ]

  return (
    <Field>
      <Field.Label>Genres</Field.Label>
      <Combobox items={genres} multiple defaultValue={['Indie', 'Folk']}>
        <Combobox.InputGroup>
          <Combobox.Value>
            {(value) => (
              <Combobox.Chips
                aria-label={value.length > 0 ? 'Selected genres' : undefined}
              >
                {value.map((genre) => (
                  <Combobox.Chip
                    key={genre}
                    aria-label={genre}
                    aria-description='Press Backspace or Delete to remove'
                  >
                    <Combobox.ChipLabel>{genre}</Combobox.ChipLabel>
                    <Combobox.ChipRemove aria-label={`Remove ${genre}`} />
                  </Combobox.Chip>
                ))}
                <Combobox.Input
                  placeholder={value.length > 0 ? '' : 'Search genres...'}
                  aria-description={
                    value.length > 0
                      ? `${value.length} selected. Press Left Arrow to move to them`
                      : undefined
                  }
                />
              </Combobox.Chips>
            )}
          </Combobox.Value>
          <Combobox.Trigger />
        </Combobox.InputGroup>
        <Combobox.Portal>
          <Combobox.Positioner>
            <Combobox.Popup>
              <Combobox.List>
                {(genre) => (
                  <Combobox.Item key={genre} value={genre}>
                    {genre}
                    <Combobox.ItemIndicator />
                  </Combobox.Item>
                )}
              </Combobox.List>
              <Combobox.Empty>No genres found</Combobox.Empty>
            </Combobox.Popup>
          </Combobox.Positioner>
        </Combobox.Portal>
      </Combobox>
    </Field>
  )
}
```

## Guidelines

### When to use Combobox

Use Combobox when the user needs to **search or filter** a list, or when options
are **loaded from an API**. The input lets users narrow results by typing. They
usually know roughly what they're looking for.

- Venue or event search
- Assignee pickers (team members from an API)
- Tag or category selection with many options
- Any list over \~15 items
- Lists that load asynchronously

### When to use Select instead

If the list is **short, fixed, and fully known** (under \~15 items), use
[Select](https://ticketsolutionsptyltd.github.io/roadie/components/select.md). Users browse rather than search. No text input
needed.

### Combobox vs Autocomplete

If the user's typed value is always valid and suggestions just help, use
[Autocomplete](https://ticketsolutionsptyltd.github.io/roadie/components/autocomplete.md). Think address fields or search bars.

| Question                 | Select          | Combobox        | [Autocomplete](https://ticketsolutionsptyltd.github.io/roadie/components/autocomplete.md) |
| ------------------------ | --------------- | --------------- | ----------------------------------------------------------------------------------------- |
| 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 `Combobox` root for built-in client-side filtering. Use
`Combobox.List` with a render function child to template each filtered item:

```tsx
<Combobox items={bands}>
  ...
  <Combobox.List>
    {(band) => <Combobox.Item value={band}>{band}</Combobox.Item>}
  </Combobox.List>
  <Combobox.Empty>No results</Combobox.Empty>
</Combobox>
```

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

The closest matches come first, so Enter picks the likeliest one. 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 "Rock" over `['Hard rock', 'Rock']` lists Rock first, so Enter picks it.
Opening the list without typing shows `items` in 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, and only an array of `items`; a
`createItems()` collection keeps its order. 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
`Combobox.Status` to announce state changes to screen readers:

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

### Chips

#### Name every chip and its remove button

**Do**

```tsx
<Combobox.Chip aria-label={genre}>
<Combobox.ChipLabel>{genre}</Combobox.ChipLabel>
<Combobox.ChipRemove aria-label={`Remove ${genre}`} />
</Combobox.Chip>
```

Label each chip with its value and each remove button with what it
removes, such as "Remove Folk".

**Don’t**

```tsx
<Combobox.ChipRemove aria-label='Remove' />
```

Don't give every remove button the same name. A screen reader can't tell
them apart.

#### Let the chips replace the placeholder

**Do**

Clear the placeholder once a value is chosen. The chips already say what
the field holds.

**Don’t**

Don't keep "Search genres..." beside three chosen genres.

## Accessibility

- **Arrow keys** move through the list; **Enter** picks the highlighted item
  and **Escape** closes the popup. Typing filters the list as you go.
- Typing puts the closest matches first and highlights the first one,
  including matches that arrive later, so **Enter** picks it straight away.
  Opening the list without typing doesn't highlight the first match, so Enter
  can't pick a value nobody chose. While a match is highlighted, the arrows
  wrap at either end. Set `autoHighlight={false}` to highlight only what the
  user moves to, or `autoHighlight='always'` to highlight the first item with
  no text too.
- The input points `aria-activedescendant` at the highlighted item, so screen
  readers read the first match as the list filters.
- With `multiple`, **Backspace** in an empty input selects the last chip, and
  a second **Backspace** removes it. A click on a chip selects it too.
  **Escape** on a chip returns focus to the input and keeps every value.
  **Left Arrow** from the start of the input moves to the chips, **Left** and
  **Right** move between them (swapped in a right-to-left layout), and
  **Backspace** or **Delete** removes the focused one. Focus moves to the
  next chip, or the previous one after the last, and returns to the input
  once no chips are left. To handle these keys yourself, call
  `event.preventBaseUIHandler()` in the input's `onKeyDown`.
- With `multiple`, **Escape** while the popup is closed clears the typed text
  and keeps every value.
- `Combobox.Chips` becomes a toolbar once it holds chips, so screen readers
  stay in focus mode while the arrows move between them. Name it with
  `aria-label` while it holds chips.
- `Combobox.ChipRemove` stays out of the tab order. Click it to remove a chip;
  from the keyboard, press Backspace on the chip. Leave it out of a `readOnly`
  combobox, where it can't remove anything.
- `aria-description` on the chip and input, as in the example, adds a hint for
  screen readers that support it. The labels must make sense without it.
- Use a `<label>` or `Combobox.Label` to name the input.
- `Combobox.ItemIndicator` shows a check on the selected item, include it for clarity.
- `Combobox.Empty` announces "no results" to screen readers automatically.
- `Combobox.Status` is a live region, use it for async status like loading or result counts.

## Hooks

### useFilter

```tsx
function useFilter(options?: FilterOptions): Filter
```

Base UI's item matcher, re-exported for filtering `items` yourself before
passing them to `Combobox` (server-side search, custom ranking) rather than
relying on the built-in client-side filter.

| Param              | Type                   | Description                                                                |
| ------------------ | ---------------------- | -------------------------------------------------------------------------- |
| `options.multiple` | `boolean`              | Whether the combobox is in multiple selection mode. Default `false`.       |
| `options.value`    | `any`                  | The current value, kept visible even while the query no longer matches it. |
| `options.locale`   | `Intl.LocalesArgument` | Locale for string comparison. Defaults to the runtime locale.              |

Returns a `Filter`:

| Field        | Type                                      | Description                                  |
| ------------ | ----------------------------------------- | -------------------------------------------- |
| `contains`   | `(item, query, itemToString?) => boolean` | Whether the item matches the query anywhere. |
| `startsWith` | `(item, query, itemToString?) => boolean` | Whether the item starts with the query.      |
| `endsWith`   | `(item, query, itemToString?) => boolean` | Whether the item ends with the query.        |

## API reference

### Combobox

```tsx
import { Combobox } from '@oztix/roadie-components/combobox'
```

- `form`: `string`. Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form.
- `filter`: `((item: Item, query: string, itemToString?: ((item: Item) => string)) => boolean) | null`. Filter function used to match items vs input query. Receives the source item, which is the derived value's item when `items` is a `createItems()` collection, and the item itself otherwise.
- `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: `<Combobox.Root inline open>` In a `Combobox.Root` > `Dialog.Root` composition, bind the Combobox's `open` and `onOpenChange` props to the `Dialog`'s `open` and `onOpenChange` state instead so the component resets its transient state (filter query, highlighted item, and input value) when the dialog closes.
- `disabled`: `boolean`. Defaults to `false`. Whether the component should ignore user interaction.
- `name`: `string`. Identifies the field when a form is submitted.
- `items`: `readonly any[] | readonly Group<any>[] | ComboboxItemCollection<Item, Value>`. The items to be displayed in the list. Can be a flat array of items, an array of groups with items, or a collection created by the `createItems()` function, which derives each item's selection value and label. 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.
- `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.
- `openOnInputClick`: `boolean`. Defaults to `true`. Whether the popup opens when clicking the input.
- `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>.
- `inputValue`: `string | number | readonly string[]`. The input value of the combobox. Use when controlled.
- `defaultInputValue`: `string | number | readonly string[]`. The uncontrolled input value when initially rendered. To render a controlled input, use the `inputValue` prop instead.
- `inputRef`: `Ref<HTMLInputElement>`. A ref to the hidden input element.
- `filteredItems`: `readonly Item[] | readonly Group<Item>[]`. 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. With a `createItems()` collection, pass source items rather than derived values. Nullish entries are not supported, as in `items`. Use when you want to control filtering logic externally with the `useFilter()` hook.
- `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.
- `autoHighlight`: `boolean | "always"`. Defaults to `true`. Whether the first match is highlighted, so Enter picks it. - `true`: once the user types, including matches that arrive later. Opening the list without typing highlights nothing. - `'always'`: whenever the list shows an item, even with no text. - `false`: only an item moved to with the arrows or the pointer.

### Combobox.Chip

- `className`: `string | ((state: ComboboxChipState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.
- `selected`: `boolean`. Shows the chip selected while focus stays elsewhere, such as in the input while its values are edited.

### Combobox.ChipLabel

No props beyond the standard HTML attributes.

### Combobox.ChipRemove

- `className`: `string | ((state: ComboboxChipRemoveState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.
- `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>`).
- `aria-label`: `string`. Required. Names the value it removes, such as "Remove Rock".

### Combobox.Chips

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

### Combobox.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.

### Combobox.Collection

No props beyond the standard HTML attributes.

### Combobox.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.

### Combobox.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.

### Combobox.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.

### Combobox.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.

### Combobox.InputGroup

- `className`: `string | ((state: ComboboxInputGroupState) => 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`.

### Combobox.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: ComboboxItemState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Combobox.ItemIndicator

- `keepMounted`: `boolean`. Defaults to `false`. Whether to keep the HTML element in the DOM when the item is not selected.
- `className`: `string | ((state: ComboboxItemIndicatorState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Combobox.Label

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

### Combobox.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.

### Combobox.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.

### Combobox.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.

### Combobox.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.

### Combobox.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.

### Combobox.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: ComboboxTriggerState) => string)`. CSS class applied to the element, or a function that returns a class based on the component's state.

### Combobox.Value

- `children`: `ReactNode | ((selectedValue: any) => ReactNode)`. Accepts a function that returns a `ReactNode` to format the selected value. Treat the value as read-only: in `multiple` mode it may be a shared frozen array when nothing is selected.
- `placeholder`: `ReactNode`. The placeholder value to display when no value is selected. This is overridden by `children` if specified, or by a null item's label in `items`.

Docs updated 20 Oct 2026.