> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Transfer

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Moves records between available and selected collections.

## When to use

Use for selecting several records while keeping both collections visible. Keep targetKeys in application state and use stable item keys.

## Examples


### Controlled target records
Select records, then use the middle action to move them. Disabled records cannot be selected.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>(['1', '4']);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      titles={['Available', 'Selected']}
      render={(item) => item.title}
    />
  );
}
```

### Controlled selection and events
selectedKeys controls checkbox state independently from targetKeys. onChange also reports the direction and moved keys.
```tsx preview
import { useState } from 'react';
import { Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  const [selected, setSelected] = useState<TransferKey[]>(['0']);
  const [event, setEvent] = useState('No records moved');
  return (
    <Stack gap="md">
      <Transfer
        dataSource={data}
        targetKeys={keys}
        selectedKeys={selected}
        onSelectChange={(source, target) => setSelected([...source, ...target])}
        onChange={(next, direction, moved) => {
          setKeys(next);
          setEvent(`${moved.length} record(s) moved ${direction}`);
        }}
        render={(item) => item.title}
      />
      <output>{event}</output>
    </Stack>
  );
}
```

### Search by multiple fields
filterOption receives the search text, item and list direction. The rendered label can differ from the searchable value.
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      showSearch={{ placeholder: 'Name or team' }}
      filterOption={(query, item) =>
        `${item.title} ${item.description}`
          .toLowerCase()
          .includes(query.toLowerCase())
      }
      render={(item) => ({
        label: (
          <span>
            {item.title} · {item.description}
          </span>
        ),
        value: `${item.title} ${item.description}`,
      })}
    />
  );
}
```

### One-way transfer and pagination
oneWay moves records right and removes them from the target list individually. Pagination applies to each list.
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>(['1', '3']);
  return (
    <Transfer
      oneWay
      pagination={{ pageSize: 4 }}
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      render={(item) => item.title}
    />
  );
}
```

### Footers and selection labels
Provide a footer for each direction and show selected counts with selectAllLabels.
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      render={(item) => item.title}
      selectAllLabels={[
        ({ selectedCount, totalCount }) =>
          `${selectedCount} / ${totalCount} available`,
        ({ selectedCount, totalCount }) =>
          `${selectedCount} / ${totalCount} selected`,
      ]}
      footer={(_, info) => (
        <small style={{ display: 'block', padding: 8 }}>
          {info?.direction === 'left'
            ? 'Choose team members'
            : 'Members added to this project'}
        </small>
      )}
    />
  );
}
```

### Custom list body
The render function receives filteredItems, selectedKeys and selection callbacks. Preserve disabled behavior in your custom controls.
```tsx preview
import { useState } from 'react';
import { Checkbox, Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      showSearch
      render={(item) => item.title}
    >
      {({ filteredItems, selectedKeys, onItemSelect, disabled }) => (
        <Stack gap="sm" style={{ padding: 12 }}>
          {filteredItems.map((item) => (
            <Checkbox
              key={item.key}
              disabled={disabled || item.disabled}
              checked={selectedKeys.includes(item.key)}
              onChange={(event) =>
                onItemSelect(item.key, event.currentTarget.checked)
              }
            >
              {item.title} <small>({item.description})</small>
            </Checkbox>
          ))}
        </Stack>
      )}
    </Transfer>
  );
}
```

### Custom keys, status and disabled state
rowKey supports records whose identifier is not named key. Source and target semantic styles can be configured separately.
```tsx preview
import { useState } from 'react';
import { Button, Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';

const data = [
  { id: 1, title: 'Design' },
  { id: 2, title: 'Engineering' },
  { id: 3, title: 'Operations' },
];
export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  const [disabled, setDisabled] = useState(false);
  return (
    <Stack gap="md">
      <Button
        variant="secondary"
        onClick={() => setDisabled((value) => !value)}
      >
        {disabled ? 'Enable' : 'Disable'}
      </Button>
      <Transfer
        dataSource={data}
        rowKey={(item) => item.id}
        targetKeys={keys}
        onChange={setKeys}
        disabled={disabled}
        status={keys.length ? undefined : 'warning'}
        render={(item) => item.title}
        styles={{
          target: { header: { background: 'var(--tao-color-bg-container)' } },
        }}
      />
      <small>Select at least one team.</small>
    </Stack>
  );
}
```

## API


### [#](#transfer)Transfer



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| render | Item content; defaults to the title, or the key when the title is omitted. | `((item: T) => RenderResult) | undefined` | `-` |

