rc-transfer-list
Transfer list that enhances a native <select multiple> into available and selected panes.
The component renders two listboxes and transfer/reorder actions in between. Available options are on the left, and selected options appear on the right. It is an older enterprise/admin UI pattern, but solves the specific problem of multiple selection within a large amount of options.
Modern use cases include user and permissions management tasks, multi-select for columns / fields / filters and list re-ordering.
Use compact when the surrounding layout should stack the available list,
actions, and selected list in one column. The component does not switch layout
automatically at viewport breakpoints.
- Package
@rcarls/rc-transfer-list- Element
<rc-transfer-list>- Native dependency
- Requires a native select child
- State model
- Native select selection
- Main events
rc-transfer-list-change- Related
- Theme previews
Installation
- npm
- Yarn
npm install @rcarls/rc-transfer-list
yarn add @rcarls/rc-transfer-list
import '@rcarls/rc-transfer-list/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 |
|---|---|---|---|---|
multiple | multiple | boolean | false | Enable multi-selection in both lists. |
compact | compact | boolean | false | Stack the panels and action toolbar into a compact one-column layout. |
availableLabel | available-label | string | 'Available' | Visible label for the available list. |
selectedLabel | selected-label | string | 'Selected' | Visible label for the selected list. |
available | JS property only | ListboxOption[] | Not specified | Available/left-hand options derived from unselected `<option>` elements. Setting this property replaces all unselected options in the backing `<select>`. Items whose values already appear in the selected list are skipped to prevent duplicate option values. |
selected | JS property only | ListboxOption[] | Not specified | Selected/right-hand options derived from selected `<option>` elements. Setting this property replaces all selected options in the backing `<select>`. Unselected options are left unchanged. |
defaultSelected | JS property only | ListboxOption[] | undefined | Not specified | Initial uncontrolled selected list. Applied before any `selected` write from the host. |
Methods
| Method | Description |
|---|---|
addSelected() | Adds the highlighted available options to the selected list. |
addAll() | Adds every available option to the selected list. |
removeSelected() | Removes the highlighted right-hand options from the selected list. |
clearSelected() | Clears the selected/right-hand list. |
moveSelected(delta: number) | Moves highlighted right-hand options by `delta` rows (-1 = up, 1 = down). |
Events
| Event | Detail type | Description |
|---|---|---|
rc-transfer-list-change | CustomEvent | Fires when the selected/right-hand list changes. |
Slots
No slots are documented in the custom elements manifest.
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--rc-transfer-list-gap | var(--rc-control-gap) | Gap between panels and the action toolbar |
--rc-transfer-list-panel-gap | var(--rc-control-gap) | Gap between a panel label and its listbox |
--rc-transfer-list-listbox-min-block-size | 10rem | Minimum block size for each listbox |
--rc-transfer-list-listbox-border | var(--rc-border) | Border around each listbox |
--rc-transfer-list-option-gap | var(--rc-item-gap) | Gap between option adornments and labels |
--rc-transfer-list-option-padding-block | var(--rc-item-padding-block) | Block padding for option rows |
--rc-transfer-list-option-padding-inline | var(--rc-item-padding-inline) | Inline padding for option rows |
--rc-transfer-list-option-selected-bg | var(--rc-highlight) | Selected option background |
--rc-transfer-list-option-selected-color | var(--rc-highlight-text) | Selected option foreground |
CSS Parts
| Part | Description |
|---|---|
root | Root layout wrapper. Reflects data-can-move-up/down. |
panel | Shared list panel surface. |
available-panel | Available/left panel. Reflects data-empty and data-has-selection. |
selected-panel | Selected/right panel. Reflects data-empty and data-has-selection. |
actions | Transfer action toolbar. |
button | Shared action button surface. |