Transfer List

FreeNew

Two lists with buttons between them to move items across, with search, select-all, move-all, disabled items and spoken results.

The full demo as documented.

Customize

Derived from this item’s props table, because it declares no controls of its own. Changes drive the preview live.

searchable

moveAll

Guide and examples

When to use it

Use it when people assign a subset of many items: channels, columns, permissions, members.

Do not use it for fewer than about eight items (checkboxes are quicker) or when order matters (use pick-list).

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/transfer-list.json

It uses button, input, which the CLI installs for you.

Usage

import { TransferList } from "@/components/ui/transfer-list"

<TransferList
  aria-label="Alert channels"
  items={[
    { id: "email", label: "Email" },
    { id: "sms", label: "Text message" },
  ]}
  value={value}
  onValueChange={setValue}
  titles={["Channels", "Alerts go to"]}
  searchable
/>

Props

Prop	Type	Default	Description
`items`	`TransferItem[]`	-	`{ id, label, description?, disabled? }`.
`value / defaultValue / onValueChange`	`string[]`	`[]`	Ids on the right, in order.
`titles`	`[string, string]`	`["Available", "Selected"]`	Names of the lists, used in labels and announcements.
`searchable`	`boolean`	`false`	A search field above each list.
`moveAll`	`boolean`	`true`	Show the move-all buttons.

Accessibility

Each list is a multiselectable listbox named by its title; options carry aria-selected and aria-disabled.
Each list has one tab stop and a select-all checkbox that shows the mixed state.
Every move is announced ("2 items moved to Selected.").
Disabled items cannot be selected or moved, also by move all.

Keyboard

ArrowDown / ArrowUp / Home / End: move within a list.
Space: select. Shift+Space or Shift+Arrow: extend a range. Ctrl+A: select all.
Enter: move the focused item to the other list.
Type a letter to jump. The buttons between the lists are in the tab order.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

TransferPane (one list) and TransferActions (the buttons) are exported. transfer-tree, transfer-table and pick-list are built from them.

Testing

The component ships with a Testing Library test (transfer-list.test.tsx) that covers its keyboard paths, roles and states.

Guide and examples

When to use it

Use it when people assign a subset of many items: channels, columns, permissions, members.

Do not use it for fewer than about eight items (checkboxes are quicker) or when order matters (use pick-list).

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/transfer-list.json

It uses button, input, which the CLI installs for you.

Usage

import { TransferList } from "@/components/ui/transfer-list"

<TransferList
  aria-label="Alert channels"
  items={[
    { id: "email", label: "Email" },
    { id: "sms", label: "Text message" },
  ]}
  value={value}
  onValueChange={setValue}
  titles={["Channels", "Alerts go to"]}
  searchable
/>

Props

Prop	Type	Default	Description
`items`	`TransferItem[]`	-	`{ id, label, description?, disabled? }`.
`value / defaultValue / onValueChange`	`string[]`	`[]`	Ids on the right, in order.
`titles`	`[string, string]`	`["Available", "Selected"]`	Names of the lists, used in labels and announcements.
`searchable`	`boolean`	`false`	A search field above each list.
`moveAll`	`boolean`	`true`	Show the move-all buttons.

Accessibility

Each list is a multiselectable listbox named by its title; options carry aria-selected and aria-disabled.
Each list has one tab stop and a select-all checkbox that shows the mixed state.
Every move is announced ("2 items moved to Selected.").
Disabled items cannot be selected or moved, also by move all.

Keyboard

ArrowDown / ArrowUp / Home / End: move within a list.
Space: select. Shift+Space or Shift+Arrow: extend a range. Ctrl+A: select all.
Enter: move the focused item to the other list.
Type a letter to jump. The buttons between the lists are in the tab order.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

TransferPane (one list) and TransferActions (the buttons) are exported. transfer-tree, transfer-table and pick-list are built from them.

Testing

The component ships with a Testing Library test (transfer-list.test.tsx) that covers its keyboard paths, roles and states.