dueling-picklist

A dueling-picklist is used to move options between two lists and is often referred to as a multi-select. Sometimes, the list options can then be re-ordered, depending on the use case.
Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
Available Languages
Selected Languages

About Dueling-Picklist

Accessibility

This component is essentially 2 ARIA listboxes side by side, so we follow the ARIA practices guide to help implement their interaction in an accessible way. Some additional details, supplementary to the ARIA guide include:

Markup

  • aria-multiselectable="true" should be set on each listbox
  • aria-selected should be placed on each role="option", and set to false by default
  • aria-labelledby is used to identify the list to the user and should point to the list label
  • aria-describedby is used to provide operation instructions for the Drag and Drop interaction
  • tabindex should be set to "0" when an item is selected and "-1" otherwise

Focus Management

  • Initially, nothing should be selected and the first item in each list should have tabindex="0"
  • When an item is focused, it becomes selected
  • When focus leaves the list, the last selected item remains selected and focusable. When focus returns to the list focus is placed on the last selected item.
  • When moving items:
    • With the move button: the items are unselected and added to the target list. The focus should remain on the move button.
    • With a keyboard shortcut: focus remains on the item, but in the target list. Since the item is focused, it is also selected.
    • If there are already selected items in the target list, they stay selected and the new items are added below them.

Keyboard Interactions

  • Each list has a single focusable option inside. There is only ever one focusable option per list and it is expected that a user will use their arrow keys, and some modifier keys, to perform all actions.
  • Because we support drag and drop re-ordering within a list, we implement the second multi-select keyboard model.
    • up and down arrows move focus and selection, with aria-selected="true". Any previously selected items are deselected.
    • shift + up and shift + down move focus and creates addition selections
    • ctrl + down or ctrl + up moves focus but selection remains where it is
    • ctrl + space toggles selection on the focused option, in addition to previous selections
    • ctrl + a selects all options in the list
    • cmd/ctrl + right and cmd/ctrl + left Moves selected items between lists
    • space toggles "Drag and Drop" mode. When in "Drag and Drop" mode:
      • up and down arrows move the selected items within the current list

Base

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category

Group Label

A Dueling Picklist should have a group label, similar to using a fieldset and legend on grouped form controls. To achieve this, wrap the Dueling Picklist in an slds-form-element and add a div with the same class names that are applied to a legend element in a fieldset, slds-form-element__label slds-form-element__legend.

Labeling the group

It is important that the slds-form-element <div> has the role="group" attribute applied, along with aria-labelledby, whose value is the ID of the visible group label.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Responsive

To make the dueling picklist responsive or use it within narrow regions, apply the class slds-dueling-picklist__column_responsive to the <div>s with class slds-dueling-picklist__column that contain options (not the columns that only contain buttons). Any items longer than the space available will truncate with ellipses.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
Available Languages
Selected Languages
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Adjusting Height

To adjust the height of the listboxes, set the height using an inline style on _both_ of the <div>s with class slds-dueling-picklist__column. If you are setting it based on a maximum number of items being shown before scrolling, you can set height = (2.25rem * numItems) + 1rem.

<div class="slds-dueling-list">
  <div class="slds-dueling-list__column">
    <span class="slds-form-element__label" id="label-1">Available Languages</span>

Edit Mode

If the user needs to select multiple options for a field, like a list of languages supported, then use a dueling picklist without the re-order arrows on the right.

Helpful Assistive Text

The assistive text content in the option-drag-label <div> should provide clear instructions on how to drag and drop with a keyboard.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
Available Languages
Selected Languages
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Selected Item

Aria Selected

aria-selected should be placed on each role="option", and set to true when the item is selected.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
Available Languages
Selected Languages
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Multiple Selected Items

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
Available Languages
Selected Languages
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Dropped Items

Aria Live

The drag-live-region <div> with aria-live="assertive" should update as items are moved to provide context about the state and location of the items.

<div class="slds-dueling-list">
  <div class="slds-assistive-text" id="drag-live-region" aria-live="assertive">Arabic and German: Moved to Selected Languages.</div>
</div>
Select Options
Arabic and German: Moved to Selected Languages.
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
Available Languages
Selected Languages
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Locked Items

If items are not able to be removed or reordered from the selected list, a lock icon appears next to the item name.

Aria Disabled and Assistive Text

For each locked item, aria-disabled="true" must be applied to .slds-listbox__option and assistive text (.slds-assistive-text) must be added to .slds-icon_container.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists. Required items must remain in the second category.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

With Reordering

If the order of the selected options matters, include the vertical arrows to the right. This allows the user to reorder the second listbox of options.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

The following examples show the process of selecting an item, moving it within a list, and dropping it in a final position.

Aria Live

Pay attention to the drag-live-region <div> witharia-live="assertive". This should update as items are moved to provide context about the state and location of the items at all times.

Item Selected

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Item Grabbed

Within a list, users are able to drag and drop an item.

Select Options
Option 5: current position 2 of 2. Press up or down arrows to move within list.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Item Moved Within a List

Select Options
Option 5: current position 1 of 2.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Item Dropped in a List

Select Options
Option 5: final position 1 of 2.
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Disabled

If the user is not able to interact with the dueling picklist, then it should be marked as disabled.

Aria Disabled

In disabled mode, both list boxes ul[role=listbox] should receive aria-disabled="true", and all directional buttons should receive the disabled attribute.

Utility Class

The class slds-is-disabled should also be applied to the divs with the class slds-dueling-list_options.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>
  <div class="slds-form-element__control">

Required

* Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
  <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">
    <abbr class="slds-required" title="required">* </abbr>Select Options</span>

With Tooltip

If some contextual information regarding the dueling picklist is needed, add a tooltip next to the group label.

Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="demo-only" style="padding-top:3rem">
  <div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
    <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">Select Options</span>

Required With Tooltip

* Select Options
Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.
First Category
Second Category
<div class="demo-only" style="padding-top:3rem">
  <div class="slds-form-element" role="group" aria-labelledby="picklist-group-label">
    <span id="picklist-group-label" class="slds-form-element__label slds-form-element__legend">

View Mode

When the user is done selecting options, or is in view mode of the field, they are presented with a comma separated list.

Selected Languages
Arabic, Chinese, English, German
<div class="slds-dueling-list">
  <div class="slds-form-element">
    <span class="slds-form-element__label">Selected Languages</span>