`<bmx-transfer-list>`

Two lists side by side - what is available and what is chosen - and the moves between them: users to a role, columns to a report, fields to an export, products to a bundle. The chosen list is the value, in order.

21 properties · 3 events · 9 methods · 12 parts

Example

Columns: Invoice number, Customer, Net amount.

Show markup

<bmx-transfer-list id="ex-tl" label="Report columns" name="columns" max="8" min="2" source-label="Available columns" target-label="In the report" description="Choose two to eight. Drag, or use Alt+Up and Alt+Down, to put them in order."></bmx-transfer-list>
<p class="note" id="ex-tl-out" role="status" style="margin: 12px 0 0">Columns: Invoice number, Customer, Net amount.</p>

<script type="module">
  await customElements.whenDefined('bmx-transfer-list');
  const list = document.getElementById('ex-tl');
  const out = document.getElementById('ex-tl-out');
  list.items = [
    { value: 'id', label: 'Invoice number', group: 'Invoice', locked: true, description: 'Always in the report' },
    { value: 'date', label: 'Invoice date', group: 'Invoice', description: 'When it was raised' },
    { value: 'due', label: 'Due date', group: 'Invoice', description: 'When payment is due' },
    { value: 'status', label: 'Status', group: 'Invoice', keywords: ['paid', 'overdue'], description: 'Draft, sent, paid or overdue' },
    { value: 'customer', label: 'Customer', group: 'Party', keywords: ['client', 'buyer'], description: 'The organisation billed' },
    { value: 'region', label: 'Région', group: 'Party', description: 'Sales region' },
    { value: 'owner', label: 'Account owner', group: 'Party', description: 'Who manages the account' },
    { value: 'net', label: 'Net amount', group: 'Money', description: 'Before tax' },
    { value: 'tax', label: 'Tax', group: 'Money', disabled: true, description: 'Not available in this report' },
    { value: 'gross', label: 'Gross amount', group: 'Money', description: 'Including tax' },
    { value: 'currency', label: 'Currency', group: 'Money', description: 'ISO 4217 code' },
    { value: 'paid', label: 'Amount paid', group: 'Money', description: 'Received so far' },
  ];
  list.value = ['id', 'customer', 'net'];
  list.addEventListener('bmxChange', async () => {
    const chosen = await list.getItems('target');
    out.textContent = `Columns: ${chosen.map(item => item.label).join(', ') || 'none'}.`;
  });
</script>

<bmx-transfer-list label="Report columns" name="columns" max="8"
  items='[{"value":"id","label":"Invoice number","group":"Invoice","locked":true},
          {"value":"date","label":"Date","group":"Invoice"},
          {"value":"customer","label":"Customer","group":"Party"}]'
  value='["id"]'></bmx-transfer-list>

Both lists filter as you type (every word, across label, description, group and keywords; accents and case ignored) and only draw the rows in view, so a hundred thousand items open and scroll as quickly as ten. Items can be grouped under headings, carry a second line, be disabled, or be locked once chosen. max stops the chosen list growing past a limit; min and required are checked as form validity.

Moving: the buttons between the lists, Enter, a double click, or dragging (mouse and pen) - from one list to the other, or within the chosen list to reorder it. bmxTransfer can be cancelled to refuse a move.

Keyboard, in either list: arrows move (the selection follows), Shift extends it, Ctrl or Command moves without selecting and Space then adds to the selection, Ctrl+A selects everything shown, Home/End and Page Up/Down jump, typing a letter finds the next item starting with it, Enter moves the selection across, Escape clears it. In the chosen list Delete moves it back and Alt+Up/Down (Alt+Home/End) reorder. Under about 34rem the lists stack.

The form receives one entry per chosen value under name.

Properties

Property	Attribute	Type	Default	Description
`description`	`description`	`string`	—	Help text below the lists.
`disabled`	`disabled`	`boolean`	`false`	Disable the control.
`dragAndDrop`	`drag-and-drop`	`boolean`	`true`	Allow dragging items between and within the lists.
`errorText`	`error-text`	`string`	—	An error supplied by the page.
`filter`	property only	`BmxTransferFilter`	—	Replaces the built-in filter matching.
`grouped`	`grouped`	`boolean`	`true`	Show group headings (in the available list, and in the chosen list when it is not `orderable`).
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it as the accessible name.
`items`	`items`	`(BmxTransferItem \| string)[] \| string`	`[]`	Every item: objects `{ value, label, description, group, keywords, disabled, locked, data }` or strings, as an array or JSON.
`label`	`label`	`string`	—	The field's label: names the whole control.
`max`	`max`	`number`	—	The most that can be chosen.
`min`	`min`	`number`	—	The fewest that must be chosen for the form to be valid.
`name`	`name`	`string`	—	The field's name: the form receives one entry per chosen value.
`orderable`	`orderable`	`boolean`	`true`	The chosen list can be put in order: buttons, Alt+arrows and dragging. When false it follows the items' own order.
`readonly`	`readonly`	`boolean`	`false`	Allow selecting and reading, but not moving.
`required`	`required`	`boolean`	`false`	At least one must be chosen.
`searchable`	`searchable`	`boolean`	`true`	A filter box above each list.
`showDescriptions`	`show-descriptions`	`boolean`	`true`	Show items' second lines.
`sourceLabel`	`source-label`	`string`	—	The available list's heading. Default: "Available".
`strings`	`strings`	`Partial<BmxTransferListStrings> \| string`	—	Words to show instead of the English ones, as an object or JSON.
`targetLabel`	`target-label`	`string`	—	The chosen list's heading. Default: "Chosen".
`value`	`value`	`string[] \| string`	`[]`	The chosen values, in order. Two-way. An array, JSON or a comma-separated list.

Events

Event	Detail	Description
`bmxChange`	`BmxTransferChangeDetail`	Fired after the chosen list changes.
`bmxSelectionChange`	`BmxTransferSelectionDetail`	Fired when the selection in either list changes.
`bmxTransfer`	`BmxTransferDetail`	Fired before items move. Cancel it to refuse the move.

Methods

Method	Signature	Description
`clearSelection`	`clearSelection(side?: BmxTransferSide) => Promise<void>`	Clear the selection in one list, or both.
`getItems`	`getItems(side: BmxTransferSide, shownOnly?: boolean) => Promise<BmxTransferItem[]>`	The items in a list, as shown (filtered) or all of them.
`getValue`	`getValue() => Promise<string[]>`	The chosen values, in order.
`moveAll`	`moveAll(from?: BmxTransferSide) => Promise<string[]>`	Move everything shown in a list across.
`moveToSource`	`moveToSource(values?: string[]) => Promise<string[]>`	Move values (default: the selection) back out of the chosen list. Resolves the values that moved.
`moveToTarget`	`moveToTarget(values?: string[]) => Promise<string[]>`	Move values (default: the selection) into the chosen list. Resolves the values that moved.
`select`	`select(side: BmxTransferSide, values: string[]) => Promise<void>`	Select values in a list (replacing the selection).
`setFilter`	`setFilter(side: BmxTransferSide, query: string) => Promise<void>`	Set the filter text of a list.
`setFocus`	`setFocus(side?: BmxTransferSide) => Promise<void>`	Focus a list.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`description`	An item's second line, and the help text under the field.
`empty`	The message in an empty list.
`filter`	A filter box.
`group`	A group heading in a list.
`header`	A list's heading row.
`label`	The label element.
`list`	A listbox.
`move`	One of them.
`moves`	The buttons between the lists.
`order`	The buttons that reorder the chosen list.
`pane`	One list with its heading and filter; also `pane-source` and `pane-target`.
`row`	An item; also `row-selected` and `row-active`.

CSS custom properties

Property	Description
`--bmx-transfer-list-height`	The height of each list's scrolling area.
`--bmx-transfer-list-label-font-size`	The label's font size.
`--bmx-transfer-list-pane-background`	A pane's background.
`--bmx-transfer-list-radius`	Corner radius of the panes.
`--bmx-transfer-list-row-height`	The height of one row (taller when items have descriptions).
`--bmx-transfer-list-selected-background`	A selected row.
`--bmx-transfer-list-support-font-size`	Font size of the description and error message.