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


<div className='grid gap-2'>
  <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>
</div>

Sizes


<div className='grid gap-2'>
  <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>
</div>

States


<div className='grid gap-4'>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Default</p>
    <Autocomplete>
      <Autocomplete.InputGroup>
        <Autocomplete.Input placeholder='Type here...' />
      </Autocomplete.InputGroup>
    </Autocomplete>
  </div>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Disabled</p>
    <Autocomplete disabled>
      <Autocomplete.InputGroup>
        <Autocomplete.Input placeholder='Type here...' />
      </Autocomplete.InputGroup>
    </Autocomplete>
  </div>
</div>

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


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


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>
              {groups.map((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. Use itemToStringValue to control what text appears in the input when an item is selected — this includes the metadata so the user sees full context.


function AutocompleteRichItems() {
  const events = [
    { name: 'Somersault Magazine Issue 02 Launch + 1st Birthday', venue: 'QUIVR, Fortitude Valley', date: '17/04/2026, 7:00 pm' },
    { name: 'Manorism - "Something I Can\'t See" Single Launch', venue: 'Shotkickers, Thornbury', date: '17/04/2026, 7:00 pm' },
    { name: 'Little Somebodies w/ The Phosphenes + Lightkeepers Trio', venue: 'Bar Open, Fitzroy', date: '26/07/2026, 7:00 pm' },
    { name: 'Our Zebra Troy - "Something Cerebral" Album Launch', venue: 'Shotkickers, Thornbury', date: '18/04/2026, 2:00 pm' },
    { name: 'In The Pines 2026', venue: 'UWA Somerville, Crawley', date: '19/04/2026, 11:00 am' },
    { name: 'SUNSET FEST SOUTH - Tribute Band Festival', venue: 'Port Beach Brewery, North Fremantle', date: '11/04/2026, 3:00 pm' },
  ]

  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.name}>
                  <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. 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>

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

Async loading

For server-side search, update the items prop as results arrive. Use Autocomplete.Status to announce state changes to screen readers:


<Autocomplete items={results} 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.

Keyboard behaviour

Arrow keys navigate the list
Enter confirms the highlighted item (or submits the form if no item is highlighted)
Escape closes the popup
Typing filters the list in real time

Accessibility

Wrap in Field and use Field.Label to name the input — this provides automatic htmlFor wiring.
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 — screen readers don't need to announce selection errors.