Combobox

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

Import

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

Examples

Default

function ComboboxDefault() {
  const bands = [
    'Powderfinger',
    'Custard',
    'Regurgitator',
    'The Go-Betweens',

Emphasis

<Combobox>
  <Combobox.InputGroup emphasis='normal'>
    <Combobox.Input placeholder='Normal emphasis' />
    <Combobox.Trigger />
  </Combobox.InputGroup>
</Combobox>

Sizes

<Combobox>
  <Combobox.InputGroup size='sm'>
    <Combobox.Input placeholder='Small' />
    <Combobox.Trigger />
  </Combobox.InputGroup>
</Combobox>

States

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

Composition

With Field

Wrap Combobox in Field for consistent layout, labels, and error handling. Field.Label's htmlFor wires directly to the Combobox input: clicking the label focuses the search field.

function ComboboxWithField() {
  const bands = [
    'Powderfinger',
    'Custard',
    'Regurgitator',
    'Violent Soho',

With groups

function ComboboxWithGroups() {
  const groups = [
    {
      value: 'Brisbane',
      items: ['Powderfinger', 'Custard', 'Regurgitator', 'The Go-Betweens', 'The Saints'],
    },

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.

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' },

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.

function ComboboxMultiple() {
  const genres = [
    'Rock',
    'Indie',
    'Hip hop',
    'Electronic',

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. 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. Think address fields or search bars.

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 Combobox root for built-in client-side filtering. Use Combobox.List with a render function child to template each filtered item:

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

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:

<Combobox
  items={results}
  filter={null}
  onInputValueChange={(value) => fetchResults(value)}
>
  ...

Chips

Name every chip and its remove button

<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".

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

Don’t

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

Let the chips replace the placeholder

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

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.

Combobox

Import

Examples

Default

Emphasis

Sizes

States

Composition

With Field

With groups

With rich items

Multiple selection

Guidelines

When to use Combobox

When to use Select instead

Combobox vs Autocomplete

Filtering

Async loading

Chips

Name every chip and its remove button

Let the chips replace the placeholder

Accessibility

Hooks

useFilter

API reference

Combobox

Import

Examples

Default

Emphasis

Sizes

States

Composition

With Field

With groups

With rich items

Multiple selection

Guidelines

When to use Combobox

When to use Select instead

Combobox vs Autocomplete

Filtering

Async loading

Chips

Name every chip and its remove button

Let the chips replace the placeholder

Accessibility

Hooks

useFilter

API reference