Combobox

A combobox combines a text field with a filterable popup list. Use it when users may type a value or pick from suggestions.

Try it

Usage

Compose RuiComboboxControl, RuiComboboxInput, RuiComboboxTrigger, and RuiComboboxListbox with RuiListboxOption children.

import { RuiCombobox, RuiComboboxControl, RuiComboboxInput, RuiComboboxTrigger, RuiComboboxListbox } from '@ecopages/radiant-ui/combobox';
import { RuiListbox, RuiListboxOption } from '@ecopages/radiant-ui/listbox';
 
<RuiCombobox value="cat" placeholder="Choose an animal">
  <RuiComboboxControl>
    <RuiComboboxInput />
    <RuiComboboxTrigger />
  </RuiComboboxControl>
  <RuiComboboxListbox>
    <RuiListbox>
      <RuiListboxOption value="cat">Cat</RuiListboxOption>
      <RuiListboxOption value="dog">Dog</RuiListboxOption>
    </RuiListbox>
  </RuiComboboxListbox>
</RuiCombobox>

Open on focus

Enable openOnFocus when the option set is small and users benefit from seeing choices immediately. Disable it for large datasets.

Allow custom values

Comboboxes accept typed input that may not match an option. Validate on submit if only predefined values are permitted.

Theming

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

Part	CSS roles
Control row (`rui-combobox__control`)	`border`, `background`, `radius-control`; `focus-ring` ring on focus-within
Input text	`on-background`, `--text-control`, `--space-control-*`
Disabled	`opacity-muted`
Popup (`rui-combobox__listbox`)	`popover` surface + `shadow-overlay` (via `rui-popover`)

Geometry shares control tokens (--size-control-*, --radius-control, --space-control-*) with RuiInput and RuiButton so form rows align. Override at the theme layer, not in component CSS.

API

RuiCombobox is a custom element (<rui-combobox>) that coordinates a slotted input row and listbox popup; the view helpers own the composed surface.

Attributes

Attribute	Type	Default	Description
`value`	`string`	`''`	Selected option value.
`label`	`string`	`''`	Accessible name when there is no visible `RuiLabel`.
`placeholder`	`string`	`''`	Placeholder text for the input.
`disabled`	`boolean`	`false`	Disable the input and trigger.
`open-on-focus`	`boolean`	`false`	Open the listbox when the input gains focus.

Slots

Slot	Description
`control`	Input row: `RuiComboboxControl` with `RuiComboboxInput` (+ optional `RuiComboboxTrigger`).
`listbox`	Popup shell: `RuiComboboxListbox` containing an embedded `RuiListbox`.

Events

Event	Detail	Description
`rui-change`	`{ value }`	Fired when an option is selected (or Esc clears the value).

View helpers

Component	Renders	Slot
`RuiComboboxControl`	Input row wrapper	`control`
`RuiComboboxInput`	Text input (`role="combobox"`)
`RuiComboboxTrigger`	Popup toggle button
`RuiComboboxListbox`	Popup shell (`rui-popover`)	`listbox`

CSS classes

Public BEM classes (documented via @cssclass):

Class	Description
`.rui-combobox`	Root surface.
`.rui-combobox__control`	Bordered control-height row.
`.rui-combobox__input`	Combobox text input.
`.rui-combobox__listbox`	Popup shell (adds `rui-popover rui-popover--listbox rui-floating`).

Theme roles

Part	CSS variables consumed
Control row	`--border`, `--background`, `--radius-control`, `--focus-ring`
Input text	`--on-background`, `--text-control`, `--space-control-x`, `--space-control-y`
Disabled	`--opacity-muted`
Popup	`--shadow-overlay` (via `rui-popover`)

Accessibility

The input exposes role="combobox" with aria-expanded reflecting popup state.
Associate a visible label via label or RuiLabel.
Announce the number of filtered results when the list changes substantially.

Getting started

Actions

Forms

Layout

Navigation

Overlays

Feedback

Data display