Autocomplete

Autocomplete filters a large option set as the user types. It is the right choice when the full list is too long to scan in a static select.

Try it

Usage

Wrap a text input, option collection, and empty state inside RuiAutocomplete. Pair it with RuiListbox and RuiListboxOption for the filtered results.

import { RuiAutocomplete, RuiAutocompleteInput, RuiAutocompleteCollection, RuiAutocompleteEmpty } from '@ecopages/radiant-ui/autocomplete';
import { RuiListbox, RuiListboxOption } from '@ecopages/radiant-ui/listbox';
 
<RuiAutocomplete sensitivity="base">
  <RuiAutocompleteInput placeholder="Search animals" />
  <RuiAutocompleteCollection>
    <RuiListbox>
      <RuiListboxOption value="cat">Cat</RuiListboxOption>
      <RuiListboxOption value="dog">Dog</RuiListboxOption>
    </RuiListbox>
  </RuiAutocompleteCollection>
  <RuiAutocompleteEmpty>No matches found.</RuiAutocompleteEmpty>
</RuiAutocomplete>

Tune filter sensitivity

Use base for standard substring matching. Choose accent or case when your locale or dataset requires looser or stricter comparison.

Control the input value

Bind inputValue when you need to reset the field after selection or sync with external search state.

Theming

Autocomplete surfaces map to semantic surface roles, never Tailwind palette steps:

Part	CSS roles
Input (`rui-autocomplete__input`)	`border`, `background`, `radius-control`, `on-background`, `space-control-*`; `focus-ring` ring
Collection region	structural only (scroll + flex)
Empty state (`rui-autocomplete__empty`)	`on-surface`

The filtered results themselves are RuiListbox / RuiListboxOption and follow the listbox surface roles. Override at the theme layer, not in component CSS.

API

RuiAutocomplete is a custom element (<rui-autocomplete>) that filters its slotted collection; the view helpers own the composed input and empty-state markup.

Attributes

Attribute	Type	Default	Description
`sensitivity`	`base` · `case` · `accent`	`base`	Filter sensitivity for substring matching.
`input-value`	`string`	`''`	Controlled filter query; when unset, reads from the slotted input.

Slots

Slot	Description
`input`	Search field (`RuiAutocompleteInput`).
(default)	Filterable collection of `[role="option"]`, `[role="menuitem"]`, or `[data-tag]` items.

View helpers

Component	Renders
`RuiAutocompleteInput`	Bordered search input (slotted into `input`).
`RuiAutocompleteCollection`	Scrollable wrapper for the filterable options.
`RuiAutocompleteEmpty`	No-results state, hidden while matches exist.

CSS classes

Public BEM classes (documented via @cssclass):

Class	Description
`.rui-autocomplete`	Filter host.
`.rui-autocomplete__input`	Bordered search input.
`.rui-autocomplete__collection`	Scrollable filterable region.
`.rui-autocomplete__empty`	No-results state.

Theme roles

Part	CSS variables consumed
Input	`--border`, `--background`, `--radius-control`, `--on-background`, `--space-control-x`, `--space-control-y`, `--focus-ring`
Empty state	`--on-surface`

Accessibility

The input exposes combobox semantics with aria-expanded tied to the listbox visibility.
Keyboard users can move through options with arrow keys; Enter selects the focused option.
Provide an accessible label via RuiLabel or aria-label on the input.

Getting started

Actions

Forms

Layout

Navigation

Overlays

Feedback

Data display