rc-select
Select-only combobox backed by a native <select>, following the WAI-ARIA Combobox pattern.
- Package
@rcarls/rc-select- Element
<rc-select>- Native dependency
- Requires a direct child native select
- State model
- Controlled or uncontrolled selection
- Main events
rc-select-openrc-select-closerc-select-change- Related
- Theme previews
Installation
- npm
- Yarn
npm install @rcarls/rc-select
yarn add @rcarls/rc-select
import '@rcarls/rc-select/define';
Live demo
Theming
The default demo mode shows the component without a package theme. Use the shared preview controls on this page to compare inherited, light, and dark color schemes or to apply the optional Material theme only inside the demo frames.
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
open | open | boolean | false | Reflects whether the popup listbox is open. |
multiple | multiple | boolean | false | Enables selection of multiple options simultaneously. |
disabled | disabled | boolean | false | Disables the trigger and prevents the popup from opening. |
placeholder | placeholder | string | '' | Text shown in the trigger when no value is selected. |
display | display | 'auto' | 'chips' | 'compact' | 'auto' | Controls how selected values appear in the trigger. - `'chips'` — each selected value renders as a removable chip. - `'compact'` — selected values are summarized as "First, +N more". - `'auto'` — uses `'chips'` on pointer devices and `'compact'` on touch. |
value | JS property only | RCSelectValue | Not specified | Current selection. Host writes update selection silently; user interaction emits `rc-select-change`. |
defaultValue | JS property only | RCSelectValue | undefined | Not specified | Initial uncontrolled selection, applied before user or native state owns the value. |
options | JS property only | ListboxOption[] | undefined | Not specified | Programmatic option source. Omit to derive options from the slotted `<select>`. |
selectedValues | JS property only | string[] | Not specified | Selected values as a consistently-array-shaped convenience getter. |
Methods
| Method | Description |
|---|---|
openPopup() | Opens the popup listbox if not already open or disabled. |
closePopup(returnFocus: unknown) | Closes the popup listbox. |
Events
| Event | Detail type | Description |
|---|---|---|
rc-select-open | CustomEvent | When the popup opens. |
rc-select-close | CustomEvent | When the popup closes. |
rc-select-change | CustomEvent | When user interaction changes selection. `detail: { value, selectedValues, selectedOptions }` |
Slots
| Name | Description |
|---|---|
(default) | Required. A native `<select>` element used for form submission and as the source of truth for options, multiple, and disabled state. |
display | Optional. Replaces the default value label in the trigger. |
toggle-indicator | Optional. Replaces the default chevron indicator. Accepts any element(s); the container shifts to inline-start in RTL via flex direction. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--rc-select-max-height | 20em | Maximum popup height. |
--rc-select-control-block-size | var(--rc-control-block-size) | Trigger block size. |
--rc-select-padding-block | var(--rc-control-padding-block) | Trigger block-axis padding. |
--rc-select-padding-inline | var(--rc-control-padding-inline) | Trigger inline-axis padding. |
--rc-select-gap | var(--rc-control-gap) | Gap between trigger content, chips, and icon. |
--rc-select-radius | var(--rc-control-radius) | Trigger border radius. |
--rc-select-border | var(--rc-border) | Trigger border. |
--rc-select-listbox-radius | var(--rc-control-radius) | Popup listbox border radius. |
--rc-select-listbox-padding-block | var(--rc-control-padding-block) | Popup listbox block padding. |
--rc-select-chip-radius | var(--rc-radius-md) | Multi-select chip border radius. |
--rc-select-chip-padding-block | 0.1em | Multi-select chip block-axis padding. |
--rc-select-chip-padding-inline | 0.3em | Multi-select chip inline-axis padding. |
--rc-select-toggle-indicator-size | 1.1em | Inline size of the toggle indicator container. |
CSS Parts
| Part | Description |
|---|---|
anchor | The flex container wrapping chips and trigger. |
trigger | The combobox trigger element (div). |
chips | The chips group container (when multiple). |
chip | Individual chip (when multiple). |
chip-label | Text label inside a chip. |
chip-remove | Remove button inside a chip. |
value-display | The text label showing selected value(s). |
toggle-indicator | The open/close indicator container. |