Dual list selector

A dual list selector displays 2 interactive lists: a list of selected items and a list of available, selectable items. Users can move items between the lists.

Examples

The dual list selector is built in a composable manner to make customization easier. The standard sub-component relationships are arranged as follows:

<DualListSelector>
  <DualListSelectorPane>
    <DualListSelectorList>
      <DualListSelectorListItem />
    </DualListSelectorList>
  </DualListSelectorPane>

  <DualListSelectorControlsWrapper>
    <DualListSelectorControl /> /* A standard Dual list selector has 4 controls */
  </DualListSelectorControlsWrapper>

  <DualListSelectorPane isChosen>
    <DualListSelectorList>
      <DualListSelectorListItem />
    </DualListSelectorList>
  </DualListSelectorPane>
</DualListSelector>

Basic

0 of 4 options selected

0 of 0 options selected

Basic with tooltips

0 of 4 options selected

0 of 0 options selected

Basic with search

0 of 4 options selected

0 of 0 options selected

Using more complex options with actions

0 of 4 options selected

0 of 0 options selected

isDisabled

With tree

0 of 7 options selected

0 of 4 options selected

Drag and drop

This example only allows reordering the contents of the "chosen" pane with drag and drop. To make a pane able to be reordered:

wrap the DualListSelectorPane in a DragDrop component
wrap the DualListSelectorList in a Droppable component
wrap the DualListSelectorListItem components in a Draggable component
define an onDrop callback which reorders the sortable options.
- The onDrop function provides the starting location and destination location for a dragged item. It should return true to enable the 'drop' animation in the new location and false to enable the 'drop' animation back to the item's old position.
- define an onDrag callback which ensures that the drag event will not cross hairs with the onOptionSelect click event set on the option. Note: the ignoreNextOptionSelect state value is used to prevent selection while dragging.

Note: Keyboard accessibility and screen reader accessibility for the DragDrop component are still in development.

0 of 3 options selected

0 of 4 options selected

Props

DualListSelector

Acts as a container for all other DualListSelector sub-components when using a composable dual list selector.
*required
Name	Type	Default	Description
children	React.ReactNode	''	Content to be rendered in the dual list selector.
className	string		Additional classes applied to the dual list selector.
id	string		ID of the dual list selector.
isTree	boolean	false	Flag indicating if the dual list selector uses trees instead of simple lists.

DualListSelectorPane

Acts as the container for a list of options that are either available or chosen, depending on the pane type (available or chosen). A search input and other actions, such as sorting, can also be passed into this sub-component.
*required
Name	Type	Default	Description
actions	React.ReactNode[]		Actions to place above the pane.
children	React.ReactNode		A dual list selector list or dual list selector tree to be rendered in the pane.
className	string	''	Additional classes applied to the dual list selector pane.
id	string	getUniqueId('dual-list-selector-pane')	ID of the pane.
isChosen	boolean	false	Flag indicating if this pane is the chosen pane.
isDisabled	boolean	false	Flag indicating whether the component is disabled.
listMinHeight	string		Minimum height of the list of options rendered in the pane. *
onSearch	(event: React.ChangeEvent<HTMLInputElement>) => void		Callback for search input. To be used when isSearchable is true.
searchInput	React.ReactNode		A search input placed above the list at the top of the pane, before actions.
status	string	''	Status to display above the pane.
title	React.ReactNode	''	Title of the pane.

DualListSelectorList

Acts as the container for DualListSelectorListItem sub-components.
*required
Name	Type	Default	Description
children	React.ReactNode		Content rendered inside the dual list selector list.

DualListSelectorListItem

Creates an individual option that can be selected and moved between the dual list selector panes. This is contained within the DualListSelectorList sub-component.
*required
Name	Type	Description
children	React.ReactNode	Content rendered inside the dual list selector.
className	string	Additional classes applied to the dual list selector.
draggableButtonAriaLabel	string	Accessible label for the draggable button on draggable list items.
id	string	ID of the option.
isDisabled	boolean	Flag indicating if the dual list selector is in a disabled state.
isDraggable	boolean	Flag indicating this item is draggable for reordering.
isSelected	boolean	Flag indicating the list item is currently selected.
onOptionSelect	(event: React.MouseEvent \| React.ChangeEvent \| React.KeyboardEvent, id?: string) => void	Callback fired when an option is selected.

DualListSelectorControlsWrapper

Acts as the container for the DualListSelectorControl sub-components.
*required
Name	Type	Description
aria-label	string	Accessible label for the dual list selector controls wrapper.
children	React.ReactNode	Content to be rendered inside of the controls wrapper.
className	string	Additional classes added to the wrapper.

DualListSelectorControl

Renders an individual control button for moving selected options between each dual list selector pane.
*required
Name	Type	Description
aria-label	string	Accessible label for the dual list selector control.
children	React.ReactNode	Content to be rendered in the dual list selector control.
className	string	Additional classes applied to the dual list selector control.
icon	React.ReactNode	Icon to be rendered in the dual list selector control.
isDisabled	boolean	Flag indicating the control is disabled.
onClick	(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void	Callback fired when dual list selector control is selected.
tooltipContent	React.ReactNode	Content to be displayed in a tooltip on hover of control.
tooltipProps	any	Additional tooltip properties passed to the tooltip.

DualListSelectorTree

Used in place of the DualListSelectorListItem sub-component when building a composable dual list selector with a tree.
*required
Name	Type	Default	Description
datarequired	DualListSelectorTreeItemData[] \| (() => DualListSelectorTreeItemData[])		Data of the tree view.
defaultAllExpanded	boolean	false	Sets the default expanded behavior.
hasBadges	boolean	false	Flag indicating if all options should have badges.
id	string		ID of the tree view.
isDisabled	boolean	false	Flag indicating if the dual list selector tree is in the disabled state.
onOptionCheck	( event: React.MouseEvent \| React.ChangeEvent<HTMLInputElement> \| React.KeyboardEvent, isChecked: boolean, itemData: DualListSelectorTreeItemData ) => void		Callback fired when an option is checked.

DualListSelectorTreeItemData

*required
Name	Type	Description
idrequired	string	ID of the option.
isCheckedrequired	boolean	Checked state of the option.
textrequired	string	Text of the option.
badgeProps	any	Additional properties to pass to the option badge.
checkProps	any	Additional properties to pass to the option checkbox.
children	DualListSelectorTreeItemData[]	Content rendered inside the dual list selector.
className	string	Additional classes applied to the dual list selector.
defaultExpanded	boolean	Flag indicating this option is expanded by default.
hasBadge	boolean	Flag indicating this option has a badge.
isDisabled	boolean	Flag indicating whether the component is disabled.
onOptionCheck	( event: React.MouseEvent \| React.ChangeEvent<HTMLInputElement> \| React.KeyboardEvent, isChecked: boolean, isChosen: boolean, itemData: DualListSelectorTreeItemData ) => void	Callback fired when an option is checked.
parentId	string	Parent ID of an option.

CSS variables

Expand or collapse column	Selector	Variable	Value

View source on GitHub