Select

Selects let users choose one or more known values from a list inside a compact trigger and popup listbox. Use a select when the value must be one of the options; use a combobox when users also need to type and filter.

Try it

Mental model

<rui-select> is a behavior host: helpers place the trigger, value, and popup; the custom element owns open state, keyboard, and selection. Options live in an embedded RuiListbox. Named regions are Composition Helpers (RuiSelectTrigger, RuiSelectClear, …), 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 (value="draft,published"). 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, not characters inside a token.

Not form-associated. Wrap in RuiField and read the value from RuiForm onSubmit. It does not appear in new FormData(form).

Usage

Pass options for the default composition, or supply children for an explicit layout.

import { RuiSelect } from '@ecopages/radiant-ui/select';
import { RuiLabel } from '@ecopages/radiant-ui/label';
 
<RuiLabel>Animal</RuiLabel>
<RuiSelect
  value="cat"
  placeholder="Select an animal"
  options={[
    { value: 'cat', label: 'Cat' },
    { value: 'dog', label: 'Dog' },
  ]}
/>Copy

The options API does not include a clear control. Add RuiSelectClear in a composed layout when the field should be resettable. Children replace the default close icon.

import {
  RuiSelect,
  RuiSelectClear,
  RuiSelectControl,
  RuiSelectListbox,
  RuiSelectToggle,
  RuiSelectTrigger,
  RuiSelectValue,
} from '@ecopages/radiant-ui/select';
import { RuiListbox, RuiListboxOption } from '@ecopages/radiant-ui/listbox';
import { RuiIconX } from '@ecopages/radiant-ui/icons';
 
<RuiSelect value="cat" placeholder="Select an animal">
  <RuiSelectControl>
    <RuiSelectTrigger>
      <RuiSelectValue />
    </RuiSelectTrigger>
    <RuiSelectClear aria-label="Clear animal selection">
      <RuiIconX />
    </RuiSelectClear>
    <RuiSelectToggle />
  </RuiSelectControl>
  <RuiSelectListbox>
    <RuiListbox embedded>
      <RuiListboxOption value="cat">Cat</RuiListboxOption>
      <RuiListboxOption value="dog">Dog</RuiListboxOption>
    </RuiListbox>
  </RuiSelectListbox>
</RuiSelect>Copy

Always set embedded on a listbox inside the popup so the select owns selection and keyboard.

Custom markup

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

import '@ecopages/radiant-ui/select';
import '@ecopages/radiant-ui/listbox';
 
<rui-select value="cat" placeholder="Select an animal">
  <div data-ref="root" class="rui-select">
    <div class="rui-select__control">
      <div data-select-trigger tabindex="0">
        <span data-select-value></span>
      </div>
      <button type="button" data-select-toggle></button>
    </div>
    <div data-select-listbox hidden>
      <rui-listbox embedded>
        <div role="option" data-value="cat">Cat</div>
        <div role="option" data-value="dog">Dog</div>
      </rui-listbox>
    </div>
  </div>
</rui-select>Copy

BEM classes are presentation-only. Nested rui-listbox must have embedded. For multi-select chips, place rui-tag-group inside [data-select-value].

Multiple selection

Set selectionMode="multiple". The default options composition shows selected values as removable tags and adds a check indicator on each option. Composed layouts place a RuiTagGroup inside RuiSelectValue, and RuiListboxOptionIndicator inside an option to replace the check.

<RuiSelect
  selectionMode="multiple"
  value={['cat', 'dog']}
  placeholder="Select animals"
  options={[
    { value: 'cat', label: 'Cat' },
    { value: 'dog', label: 'Dog' },
  ]}
/>Copy

The popup stays open while options are toggled. Pass shouldCloseOnSelect to close after each choice.

Searchable lists

Wrap the embedded listbox in RuiAutocomplete and add RuiSelectSearch when the collection is long. Opening the popup moves focus into the search field.

Trigger kind

triggerKind controls what opens the listbox (same attribute name as RuiCombobox; select supports only focus and manual):

Theming

Select surfaces map to semantic surface roles, never Tailwind palette steps. Override at the theme layer, not in component CSS.

Geometry shares control tokens (--size-control-*, --radius-control, --space-control-*) with RuiInput and RuiButton.

Customization of icons is through Composition Helper children, not CSS variables: pass children to RuiSelectToggle, RuiSelectClear, and RuiListboxOptionIndicator.

Accessibility

• The trigger exposes role="combobox", aria-expanded, and aria-haspopup="listbox".
• Multiple mode marks the popup listbox aria-multiselectable="true".
• RuiSelectClear needs an accessible name (aria-label="Clear selection" by default). Clicking it clears the value and returns focus to the trigger.
• Provide a visible label. The placeholder is not a substitute.

API

RuiSelect is a custom element (<rui-select>) wrapping a button trigger and an embedded RuiListbox. It is not form-associated.

Attributes (<rui-select>)

Light-DOM contract

Do not set role, aria-expanded, or tabIndex on the trigger. Nested hosts: rui-listbox (embedded), rui-tag-group in [data-select-value], optional rui-autocomplete in the listbox.

Events

View helpers

CSS classes

Theme roles