Skip to main content

Transfer

A transfer is used to make complex selections from a list of options.

Demo

Usage

A transfer is made up of two lists. The source list that shows the available options and the picked list that shows the chosen options. Options can be transferred between lists with the middle buttons or by double-clicking an option.

When to use

  • Choose from many items. Use a transfer if a user needs to choose from many items. Transfers can work for hundreds of thousands of items.
  • Ordered selections. Use a transfer if chosen options need to have a specific order.
  • Choose from several groups. Use a transfer if a user needs to choose from several groups into a single set of chosen options.

When not to use

  • Choosing from a few items. Don't use a transfer to choose from a few options. Use a Select instead.

Options

For all the demo's below, transferOptions is an array of objects with the following shape:

;[
{
label: 'ANC 1st visit',
value: 'anc_1st_visit',
},
]

The onChange and selected properties are created like this:

const [selected, setSelected] = useState()
const onChange = (payload) => setSelected(payload.selected)
Demo
<Transfer
options={transferOptions}
selected={selected}
leftHeader={<Header label="Available options" />}
rightHeader={<Header label="Selected options" />}
onChange={onChange}
/>

The header component in this case is a simple h4 element.

  • Use headers for titles that make it clear what the transfer options are.
  • Source list headers could also contain group filters.
Demo
<Transfer
options={transferOptions}
selected={selected}
leftFooter={<Footer />}
onChange={onChange}
/>

The footer component is as follows:

<a
href="#"
style={{
color: 'grey',
padding: '8px 0',
display: 'block',
}}
>
Reload list
</a>
  • Use footers for actions that apply to a list, like Reload items.

Reordering

Demo
<Transfer
enableOrderChange
options={transferOptions}
selected={selected}
onChange={onChange}
/>
  • Allow reordering if the order of the chosen options has meaning or consequences.

Filtering

Demo
<Transfer
filterable
filterPlaceholder="Search for an option"
options={transferOptions}
selected={selected}
onChange={onChange}
/>
  • Use filtering to help a user find options in the source list.

Loading

Demo
  • Different types of data will need different loading strategies.
  • Use a Loader to block interaction if using the transfer while loading is taking place can cause problems.
  • A common pattern is loading more options as a user scrolls. See the Transfer: Infinite Loading recipe for more information.

API Reference

TransferOption

Usage

To use TransferOption, you can import the component from the @dhis2/ui library

import { TransferOption } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
labelnode*
valuestring*
classNamestring
dataTeststring'dhis2-uicore-transferoption'
disabledboolean
highlightedboolean
onClickfunction
onDoubleClickfunction

Transfer

Usage

To use Transfer, you can import the component from the @dhis2/ui library

import { Transfer } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
optionsarrayOf({<br/> "label": "string",<br/> "value": "string",<br/> "disabled": "boolean"<br/>})*
onChangefunction*
addAllTextstring
addIndividualTextstring
classNamestring
dataTeststring'dhis2-uicore-transfer'
disabledboolean
enableOrderChangeboolean
filterCallbackfunctiondefaultFilterCallback
filterCallbackPickedfunctiondefaultFilterCallback
filterLabelstring
filterLabelPickedstring
filterPlaceholderstring
filterPlaceholderPickedstring
filterableboolean
filterablePickedboolean
heightstring'240px'
hideFilterInputboolean
hideFilterInputPickedboolean
initialSearchTermstring''
initialSearchTermPickedstring''
leftFooternode
leftHeadernode
loadingboolean
loadingPickedboolean
maxSelections1 │ InfinityInfinity
optionsWidthstring'320px'
removeAllTextstring
removeIndividualTextstring
renderOptionfunction(option) => <TransferOption {...option} />
rightFooternode
rightHeadernode
searchTermstring
searchTermPickedstring
selectedarrayOf(string)[]
selectedEmptyComponentnode
selectedWidthstring'320px'
sourceEmptyPlaceholdernode
onEndReachedfunction
onEndReachedPickedfunction
onFilterChangefunction
onFilterChangePickedfunction