react-transfer-list

React Transfer List

A customizable Transfer List supporting drag and drop.

What is a transfer list?

A transfer list is a user interface component that allows users to move items between two lists. Typically, the component displays two lists side by side, with items that can be moved from one list to the other. The user can select one or more items in the source list and move them to the destination list by clicking a button or dragging and dropping them. Transfer lists are commonly used in web and mobile applications for tasks such as selecting items for a shopping cart or assigning tasks to team members. They perform a simular function to a multiple select, but offer certain trade-offs.

Transfer lists are generally more usable when the list of options is long or when the user needs to select multiple items from the list. Multi-select dropdowns can become unwieldy when the list of options is long, as the user needs to scroll through the list to find the desired options. Transfer lists allow the user to see all the available options at once and to move the selected items to the destination list, which can make the selection process faster and more efficient. Additionally, transfer lists can allow users to manually specify the order of selected items, which could be important in some cases, such as when selecting columns to display on a table.

Feature	Multi Select Dropdown	Transfer List
Space on screen	Compact	Large
Can see all selected items at once	No	Yes
Can choose order of items	No	Yes

Basic Example Visualisation (not interactive)

Install

npm i react-transfer-list

Features

• Highly Customizable
• Only requires emotion and React

Documentation

Usage

TransferList

<TransferList /> is the top level component for holding lists that can exchange items.

import { useCallback, useState } from 'react';
import { TransferList, TransferListList } from 'react-transfer-list';

const App = () => {
  const initialIds: Record<string, string[]> = {
    first: Array.from({ length: 10 }).map((_, i) => String(i + 1)),
  };
  const [ids, setIds] = useState(initialIds);

  const handleChange = useCallback((listId: string, ids: string[]) => {
    setIds((orig) => {
      orig[listId] = [...ids];
      return {...orig};
    });
  }, []);

  return (
    <TransferList ids={ids} onChange={handleChange}>
      <TransferListList
        id="first"
        style={{ height: '100%', background: 'beige', margin: '10px' }}
      />
      <TransferListList
        id="second"
        style={{ height: '100%', background: 'aliceblue', margin: '10px' }}
      />
    </TransferList>
  );
};

Adding buttons

To add buttons controlling behaviour, add click handlers to directly manipulate the ids. For example, to transfer all items from one list to another, you could use the following click handler

const transferAll = (from: string, to: string) => {
    handleChange(to, ids[from] ?? []);
    handleChange(from, []);
  }

Properties

Property	PropType	Required	Default	Description
ids	Record<string, string[]>	yes		The ids of the lists and the respective ids of each item in each list.
onChange	``			Called when a request to change the items in a list is made.

TransferListList

<TransferListList /> are lists that can exchange items within a <TransferList /> .

Properties

Property	PropType	Required	Default	Description
id	string	yes		The id of the list.
dragHandleComponent	``			Specify a custom component to render a drag handle.
listComponent	``			Specify a custom component to render the list container. Defaults to a ol element
listItemComponent	``			Specify a custom component to render the list item container. Defaults to a li element
listItemBodyComponent	``			Specify a custom component to render the body of each list item. Defaults to a span element containing the id of the item.
options	``			Additional configuration options for drag and drop behaviour.

###ReorderableList

<ReorderableList /> is a single list of items whose order can be updated by drag and drop.

import { useCallback, useState } from 'react';
import { ReorderableList } from 'react-transfer-list';

const App = () => {
  const [ids, setIds] = useState<string[]>(['1', '2', '3']);
  const handleChange = useCallback((ids: string[]) => {
    setIds(ids);
  }, []);
  return <ReorderableList ids={ids} onChange={handleChange} />;
};

Properties

Property	PropType	Required	Default	Description
ids	string[]	yes		The ids of the items in the list.
onChange	``	yes		Called when a request to change the order of the items is made.
dragHandleComponent	``			Specify a custom component to render a drag handle.
listComponent	``			Specify a custom component to render the list container. Defaults to a ol element
listItemComponent	``			Specify a custom component to render the list item container. Defaults to a li element
listItemBodyComponent	``			Specify a custom component to render the body of each list item. Defaults to a span element containing the id of the item.
options	``			Additional configuration options for drag and drop behaviour.

Storybook

Visit The Storybook Page