Autocomplete

A text input with suggestions that optionally complete your typing.

Import

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

Examples

Default

function AutocompleteDefault() {
  const cities = [
    'Brisbane',
    'Sydney',
    'Melbourne',
    'Perth',

Emphasis

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

Sizes

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

States

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

Composition

With Field

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

function AutocompleteWithField() {
  const cities = [
    'Brisbane',
    'Sydney',
    'Melbourne',
    'Perth',

With trigger

function AutocompleteWithTrigger() {
  const cities = [
    'Brisbane',
    'Sydney',
    'Melbourne',
    'Perth',

With groups

function AutocompleteWithGroups() {
  const groups = [
    {
      value: 'New South Wales',
      items: ['Sydney', 'Newcastle', 'Wollongong', 'Central Coast'],
    },

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.

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

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. If the list is short and fixed, use Select.

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:

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

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:

<Autocomplete
  items={results}
  filter={null}
  onValueChange={(value) => fetchResults(value)}
>
  ...

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

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.

Autocomplete

Import

Examples

Default

Emphasis

Sizes

States

Composition

With Field

With trigger

With groups

With rich items

Guidelines

When to use Autocomplete

When to use Combobox or Select instead

Filtering

Async loading

Mode

Keyboard behaviour

Accessibility

Hooks

useFilteredItems

API reference

Autocomplete

Import

Examples

Default

Emphasis

Sizes

States

Composition

With Field

With trigger

With groups

With rich items

Guidelines

When to use Autocomplete

When to use Combobox or Select instead

Filtering

Async loading

Mode

Keyboard behaviour

Accessibility

Hooks

useFilteredItems

API reference