Dual list selector

A dual list selector allows users to select and move items from one list of available items to another list of selected items. Unlike a select list, a dual list selector separates the available options and the selected options into two separate lists, which allows users to easily scan the items they selected.

Examples

Basic

Available options
0 of 4 items selected
  • Option 1
  • Option 2
  • Option 3
  • Option 4
Chosen options
0 of 0 items selected

    Basic with tooltips

    Available options
    0 of 4 items selected
    • Option 1
    • Option 2
    • Option 3
    • Option 4
    Chosen options
    0 of 0 items selected

      Using more complex options with actions

      Available options
      0 of 4 items selected
      • Option 1
      • Option 3
      • Option 4
      • Option 2
      Chosen options
      0 of 0 items selected

        With tree

        Available options
        0 of 7 items selected
        • Folder 14
        • Option 5
        • Folder 2
        Chosen options
        0 of 4 items selected
        • Chosen Folder 14

        Composable structure

        The dual list selector can also be 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>

        Composable dual list selector

        Available
        0 of 7 options selected
        • Apple
        • Banana
        • Pineapple
        • Orange
        • Grape
        • Peach
        • Strawberry
        Chosen
        0 of 0 options selected

        Composable with drag and drop

        Note: There is a new recommended drag and drop implementation with full keyboard functionality, which replaces this implementation. To adhere to our new recommendations, refer to the drag and drop demos.

        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.

        Keyboard and screen reader accessibility for the <DragDrop> component is still in development.

        Available
        0 of 3 options selected
        • Apple
        • Banana
        • Pineapple
        Chosen
        0 of 4 options selected
        • Orange
        • Grape
        • Peach
        • Strawberry

        Composable with tree

        Available
        0 of 7 options selected
        • Fruits4
        • Bread
        • Vegetables2
        Chosen
        0 of 4 options selected
        • Proteins4

        Props

        DualListSelector

        Acts as a container for all other DualListSelector sub-components when using a composable dual list selector.
        *required
        NameTypeDefaultDescription
        addAll(newAvailableOptions: React.ReactNode[], newChosenOptions: React.ReactNode[]) => voidOptional callback for the dynamically built add all button
        addAllAriaLabelstring'Add all'Accessible label for the dynamically built add all button
        addAllTooltipReact.ReactNodeTooltip content for the dynamically built add all button
        addAllTooltipPropsanyAdditonal tooltip properties for the dynamically built add all tooltip
        addSelected(newAvailableOptions: React.ReactNode[], newChosenOptions: React.ReactNode[]) => voidOptional callback for the dynamically built add selected button
        addSelectedAriaLabelstring'Add selected'Accessible label for the dynamically built add selected button
        addSelectedTooltipReact.ReactNodeTooltip content for the dynamically built add selected button
        addSelectedTooltipPropsanyAdditonal tooltip properties for the dynamically built add selected tooltip
        availableOptionsReact.ReactNode[] | DualListSelectorTreeItemData[][]Options to display in the dynamically built available options pane. When using trees, the options should be in the DualListSelectorTreeItemData[] format.
        availableOptionsActionsReact.ReactNode[]Actions to be displayed above the dynamically built available options pane.
        availableOptionsSearchAriaLabelstring'Available search input'Accessible label for the search input on the dynamically built available options pane.
        availableOptionsStatusstringStatus message to display above the dynamically built available options pane.
        availableOptionsTitlestring'Available options'Title applied to the dynamically built available options pane.
        childrenReact.ReactNode''Content to be rendered in the dual list selector. Panes & controls will not be built dynamically when children are provided.
        chosenOptionsReact.ReactNode[] | DualListSelectorTreeItemData[][]Options to display in the dynamically built chosen options pane. When using trees, the options should be in the DualListSelectorTreeItemData[] format.
        chosenOptionsActionsReact.ReactNode[]Actions to be displayed above the dynamically built chosen options pane.
        chosenOptionsSearchAriaLabelstring'Chosen search input'Accessible label for the search input on the dynamically built chosen options pane.
        chosenOptionsStatusstringStatus message to display above the dynamically built chosen options pane.
        chosenOptionsTitlestring'Chosen options'Title applied to the dynamically built chosen options pane.
        classNamestringAdditional classes applied to the dual list selector.
        controlsAriaLabelstring'Selector controls'Accessible label for the dynamically built controls between the two panes.
        filterOption(option: React.ReactNode, input: string) => booleanOptional filter function for custom filtering based on search string. Used with a dynamically built search input.
        idstringId of the dual list selector.
        isDisabledbooleanfalseFlag indicating if the dual list selector is in a disabled state
        isSearchablebooleanFlag indicating a search bar should be included above both the dynamically built available and chosen panes.
        isTreebooleanfalseFlag indicating if the dual list selector uses trees instead of simple lists
        onAvailableOptionsSearchInputChanged(event: React.FormEvent<HTMLInputElement>, value: string) => voidA callback for when the search input value for the dynamically built available options changes.
        onChosenOptionsSearchInputChanged(event: React.FormEvent<HTMLInputElement>, value: string) => voidA callback for when the search input value for the dynamically built chosen options changes.
        onListChange( event: React.MouseEvent<HTMLElement>, newAvailableOptions: React.ReactNode[], newChosenOptions: React.ReactNode[] ) => voidCallback fired every time dynamically built options are chosen or removed
        onOptionCheck( event: React.MouseEvent | React.ChangeEvent<HTMLInputElement> | React.KeyboardEvent, checked: boolean, checkedId: string, newCheckedItems: string[] ) => voidOptional callback fired when a dynamically built option is checked
        onOptionSelect( event: React.MouseEvent | React.ChangeEvent | React.KeyboardEvent, index: number, isChosen: boolean, id: string, itemData: any, parentData: any ) => voidOptional callback fired when a dynamically built option is selected
        removeAll(newAvailableOptions: React.ReactNode[], newChosenOptions: React.ReactNode[]) => voidOptional callback for the dynamically built remove all button
        removeAllAriaLabelstring'Remove all'Accessible label for the dynamically built remove all button
        removeAllTooltipReact.ReactNodeTooltip content for the dynamically built remove all button
        removeAllTooltipPropsanyAdditonal tooltip properties for the dynamically built remove all tooltip
        removeSelected(newAvailableOptions: React.ReactNode[], newChosenOptions: React.ReactNode[]) => voidOptional callback for the dynamically built remove selected button
        removeSelectedAriaLabelstring'Remove selected'Accessible label for the dynamically built remove selected button
        removeSelectedTooltipReact.ReactNodeTooltip content for the dynamically built remove selected button
        removeSelectedTooltipPropsanyAdditonal tooltip properties for the dynamically built remove selected tooltip

        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
        NameTypeDefaultDescription
        actionsReact.ReactNode[]Actions to place above the pane.
        childrenReact.ReactNodeA dual list selector list or dual list selector tree to be rendered in the pane.
        classNamestring''Additional classes applied to the dual list selector pane.
        idstringgetUniqueId('dual-list-selector-pane')Id of the pane.
        isChosenbooleanfalseFlag indicating if this pane is the chosen pane.
        isDisabledbooleanfalseFlag indicating whether the component is disabled.
        listMinHeightstringMinimum height of the list of options rendered in the pane. *
        onSearch(event: React.ChangeEvent<HTMLInputElement>) => voidCallback for search input. To be used when isSearchable is true.
        searchInputReact.ReactNodeA search input placed above the list at the top of the pane, before actions.
        statusstring''Status to display above the pane.
        titleReact.ReactNode''Title of the pane.

        DualListSelectorList

        Acts as the container for DualListSelectorListItem sub-components.
        *required
        NameTypeDefaultDescription
        childrenReact.ReactNodeContent 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
        NameTypeDefaultDescription
        childrenReact.ReactNodeContent rendered inside the dual list selector.
        classNamestringAdditional classes applied to the dual list selector.
        draggableButtonAriaLabelstringAccessible label for the draggable button on draggable list items
        idstringID of the option.
        isDisabledbooleanFlag indicating if the dual list selector is in a disabled state
        isDraggablebooleanFlag indicating this item is draggable for reordring
        isSelectedbooleanFlag indicating the list item is currently selected.
        onOptionSelect(event: React.MouseEvent | React.ChangeEvent | React.KeyboardEvent, id?: string) => voidCallback fired when an option is selected.

        DualListSelectorControlsWrapper

        Acts as the container for the DualListSelectorControl sub-components.
        *required
        NameTypeDefaultDescription
        aria-labelstringAccessible label for the dual list selector controls wrapper.
        childrenReact.ReactNodeAnything that can be rendered inside of the wrapper.
        classNamestringAdditional classes added to the wrapper.

        DualListSelectorControl

        Renders an individual control button for moving selected options between each dual list selector pane.
        *required
        NameTypeDefaultDescription
        aria-labelstringAccessible label for the dual list selector control.
        childrenReact.ReactNodeContent to be rendered in the dual list selector control.
        classNamestringAdditional classes applied to the dual list selector control.
        isDisabledbooleanFlag indicating the control is disabled.
        onClick(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => voidCallback fired when dual list selector control is selected.
        tooltipContentReact.ReactNodeContent to be displayed in a tooltip on hover of control.
        tooltipPropsanyAdditional 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
        NameTypeDefaultDescription
        datarequiredDualListSelectorTreeItemData[] | (() => DualListSelectorTreeItemData[])Data of the tree view
        defaultAllExpandedbooleanfalseSets the default expanded behavior
        hasBadgesbooleanfalseFlag indicating if all options should have badges
        idstringID of the tree view
        isDisabledbooleanfalseFlag 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 ) => voidCallback fired when an option is checked

        DualListSelectorTreeItemData

        *required
        NameTypeDefaultDescription
        idrequiredstringID of the option
        isCheckedrequiredbooleanChecked state of the option
        textrequiredstringText of the option
        badgePropsanyAdditional properties to pass to the option badge
        checkPropsanyAdditional properties to pass to the option checkbox
        childrenDualListSelectorTreeItemData[]Content rendered inside the dual list selector.
        classNamestringAdditional classes applied to the dual list selector.
        defaultExpandedbooleanFlag indicating this option is expanded by default.
        hasBadgebooleanFlag indicating this option has a badge
        isDisabledbooleanFlag indicating whether the component is disabled.
        onOptionCheck( event: React.MouseEvent | React.ChangeEvent<HTMLInputElement> | React.KeyboardEvent, isChecked: boolean, isChosen: boolean, itemData: DualListSelectorTreeItemData ) => voidCallback fired when an option is checked
        parentIdstringParent id of an option

        CSS variables

        Expand or collapse columnSelectorVariableValue

        View source on GitHub