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
- Usage rulesTheme previews
Installation
- npm
- Yarn
- pnpm
npm install @rcarls/rc-webcomponents@next
yarn add @rcarls/rc-webcomponents@next
pnpm add @rcarls/rc-webcomponents@next
import '@rcarls/rc-webcomponents/rc-transfer-list/define';
Usage
Wrap a native <select multiple>. Its selected options form the selected list, in order, so form
submission sends the values shown there.
<rc-transfer-list available-label="Available planets" selected-label="Mission route">
<select name="planets" multiple>
<option value="mercury">Mercury</option>
<option value="venus" selected>Venus</option>
<option value="earth">Earth</option>
</select>
</rc-transfer-list>
Live demo
Accessibility
Each side is an rc-listbox, named by available-label and
selected-label, with its own list navigation and selection. The action buttons are native
buttons in an rc-toolbar, so arrow keys move between them.
These shortcuts also work while focus is in either list:
| Key | Action |
|---|---|
| Alt+Right Arrow | Adds the highlighted available options. |
| Alt+Left Arrow | Removes the highlighted selected options. |
| Alt+Up Arrow, Alt+Down Arrow | Moves the highlighted selected options up or down. |
| Enter | In a single-select available list, adds the highlighted option. |
| Delete | In the selected list, removes the highlighted options. |
Alt+Left and Alt+Right swap in right-to-left text, where the lists swap sides.
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.
Localization
Built-in text follows the element's own lang, else <html lang>. Override it with
messages, or register it for every instance under rc-transfer-list: available, selected, actions, add, addAll, remove, clear, moveUp, moveDown. See
Localization.
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 | undefined | Not specified | Visible label for the available list. Defaults to the `available` message. |
selectedLabel | selected-label | string | undefined | Not specified | Visible label for the selected list. Defaults to the `selected` message. |
messages | JS property only | Partial<RCTransferListMessages> | undefined | Not specified | Built-in text overrides; unset keys fall back to registered text, then English. |
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. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--rc-transfer-list-gap | var(--rc-control-gap, 0.75rem) | Gap between panels and the action toolbar |
--rc-transfer-list-panel-gap | var(--rc-control-gap, 0.35rem) | 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, 1px solid ButtonBorder) | Border around each listbox |
--rc-transfer-list-listbox-radius | var(--rc-control-radius, 0.125rem) | Corner radius of each listbox |
--rc-transfer-list-listbox-bg | var(--rc-surface, Canvas) | Background of each listbox |
--rc-transfer-list-listbox-color | var(--rc-field-text, FieldText) | Text color of each listbox |
--rc-transfer-list-option-gap | var(--rc-item-gap, 0.4em) | Gap between option adornments and labels |
--rc-transfer-list-option-padding-block | var(--rc-item-padding-block, 0.3em) | Block padding for option rows |
--rc-transfer-list-option-padding-inline | var(--rc-item-padding-inline, 0.75em) | Inline padding for option rows |
--rc-transfer-list-option-selected-bg | var(--rc-highlight, Highlight) | Selected option background |
--rc-transfer-list-option-selected-color | var(--rc-highlight-text, HighlightText) | Selected option foreground |
--rc-transfer-list-option-hover-bg | var(--rc-transfer-list-option-selected-bg, var(--rc-highlight, Highlight)) | Hovered/active option background |
--rc-transfer-list-option-hover-color | var(--rc-transfer-list-option-selected-color, var(--rc-highlight-text, HighlightText)) | Hovered/active 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. |
label | Shared panel label surface. |
available-label | Label for the available panel. |
selected-label | Label for the selected panel. |
listbox | Shared listbox surface. |
available-listbox | The available/left `rc-listbox`. |
selected-listbox | The selected/right `rc-listbox`. |
actions | Transfer action toolbar. |
button | Shared action button surface. |
add-button | Moves highlighted available options to the selected list. |
add-all-button | Moves every available option to the selected list. |
remove-button | Moves highlighted selected options back to the available list. |
clear-button | Moves every selected option back to the available list. |
move-up-button | Moves highlighted selected options up. |
move-down-button | Moves highlighted selected options down. |