Combobox

A combobox combines a text field with a filterable popup list. Use it when users need to search a known set of options. Typed text filters the list; only selecting an option commits a value.

Try it

Mental model

<rui-combobox> is a behavior host: helpers place the input row and popup; the custom element owns filtering, keyboard, and selection. Options live in an embedded RuiListbox, usually wrapped in RuiAutocomplete. Named regions are Composition Helpers, not HTML slots.

The live value property is always a string[] ([] when nothing is selected). The HTML attribute is those tokens as a comma-separated string. JSX may pass a string or an array; a string is parsed as CSV. rui-change emits { value: string[] }. Commas in the attribute are delimiters.

Important: typing does not create a custom value. Enter with no active option closes the popup. Escape while closed clears the committed value and the input. If only predefined options are valid, that is already the runtime contract — do not expect free-text to be stored on value.

Not form-associated. Wrap in RuiField and read the selected tokens from RuiForm onSubmit. The filter textbox is not listed in new FormData(form).

Usage

Pass options for the default composition, or compose the helpers explicitly. Always set embedded on the listbox inside the popup.

import {
  RuiCombobox,
  RuiComboboxClear,
  RuiComboboxControl,
  RuiComboboxInput,
  RuiComboboxListbox,
  RuiComboboxTrigger,
} from '@ecopages/radiant-ui/combobox';
import { RuiAutocomplete, RuiAutocompleteCollection, RuiAutocompleteEmpty } from '@ecopages/radiant-ui/autocomplete';
import { RuiListbox, RuiListboxOption } from '@ecopages/radiant-ui/listbox';
import { RuiIconX } from '@ecopages/radiant-ui/icons';
 
<RuiCombobox value="cat" placeholder="Choose an animal">
  <RuiComboboxControl>
    <RuiComboboxInput />
    <RuiComboboxClear aria-label="Clear animal selection">
      <RuiIconX />
    </RuiComboboxClear>
    <RuiComboboxTrigger />
  </RuiComboboxControl>
  <RuiComboboxListbox>
    <RuiAutocomplete>
      <RuiAutocompleteCollection>
        <RuiListbox embedded>
          <RuiListboxOption value="cat">Cat</RuiListboxOption>
          <RuiListboxOption value="dog">Dog</RuiListboxOption>
        </RuiListbox>
        <RuiAutocompleteEmpty>No results found.</RuiAutocompleteEmpty>
      </RuiAutocompleteCollection>
    </RuiAutocomplete>
  </RuiComboboxListbox>
</RuiCombobox>Copy

Children on RuiComboboxClear and RuiComboboxTrigger replace the default SVGs. For decorated options, set label on RuiListboxOption so the committed input text stays clean of icons and indicators.

Custom markup

<rui-combobox> coordinates any light-DOM tree that matches its query contract. The Rui* helpers stamp these targets; they are not required.

import '@ecopages/radiant-ui/combobox';
import '@ecopages/radiant-ui/listbox';
 
<rui-combobox value="cat" placeholder="Choose an animal">
  <div data-ref="root" class="rui-combobox">
    <div class="rui-combobox__control">
      <input type="text" data-combobox-input data-autocomplete-input />
      <button type="button" data-combobox-trigger></button>
    </div>
    <div data-combobox-listbox hidden>
      <rui-listbox embedded>
        <div role="option" data-value="cat">Cat</div>
      </rui-listbox>
    </div>
  </div>
</rui-combobox>Copy

Multiple selection

selectionMode="multiple" toggles known options and keeps the popup open. Selected options render as removable chips. Typed text only filters; it is not appended as a token.

<RuiCombobox
  selectionMode="multiple"
  value={['ca', 'ny']}
  options={[
    { value: 'ca', label: 'California' },
    { value: 'ny', label: 'New York' },
  ]}
/>Copy

For composed layouts, place RuiComboboxValue (with a RuiTagGroup) before RuiComboboxInput. Add RuiListboxOptionIndicator inside an option to replace the selected checkmark.

Trigger kind

triggerKind controls what opens the listbox:

Theming

Combobox surfaces map to semantic surface roles, never Tailwind palette steps. Override at the theme layer.

Icon swaps are Composition Helper children, not CSS variables.

API

RuiCombobox is a custom element (<rui-combobox>) that coordinates a composed input row and listbox popup. It is not form-associated.

Attributes

Light-DOM contract

Nested hosts: rui-listbox (embedded), rui-tag-group in [data-combobox-value], optional rui-autocomplete.

Events

View helpers

CSS classes

Theme roles

Accessibility

• The input exposes role="combobox" with aria-expanded reflecting popup state.
• Multiple mode marks the popup listbox aria-multiselectable="true"; each known option toggles aria-selected.
• Compose RuiComboboxClear for an explicit clear action; it restores focus to the input.
• Associate a visible label via RuiLabel or label.