Component Blueprints

Dueling Picklist

Lightning Component
  • HTML/CSS:Dev Ready
  • Layout:Desktop Only

Sections

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/Ctrl 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/Ctrl 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/Ctrl 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">
    <div class="slds-dueling-list">

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). The dueling picklist will take up all available horizontal space, and any items longer than the available space will truncate with an ellipsis.

Select Options
Press space bar when on an item, to move it within the list. Cmd/Ctrl 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">
    <div class="slds-dueling-list">

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>
    <div class="slds-dueling-list__options" style="height:10rem">...</div>
  </div>
  <div class="slds-dueling-list__column">...</div>
  <div class="slds-dueling-list__column">
    <span class="slds-form-element__label" id="label-2">Selected Languages</span>
    <div class="slds-dueling-list__options" style="height:10rem">...</div>
  </div>
</div>

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. See the keyboard interactions section above for modifier key information.

Select Options
Press space bar when on an item, to move it within the list. Cmd/Ctrl 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">
    <div class="slds-dueling-list">

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/Ctrl 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">
    <div class="slds-dueling-list">

Multiple Selected Items#

Select Options
Press space bar when on an item, to move it within the list. Cmd/Ctrl 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">
    <div class="slds-dueling-list">

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/Ctrl 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">
    <div class="slds-dueling-list">

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/Ctrl 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">
    <div class="slds-dueling-list">

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/Ctrl 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">
    <div class="slds-dueling-list">

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> with aria-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/Ctrl 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">
    <div class="slds-dueling-list">

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">
    <div class="slds-dueling-list">

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">
    <div class="slds-dueling-list">

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/Ctrl 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">
    <div class="slds-dueling-list">

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/Ctrl 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">
    <div class="slds-dueling-list">

Required#

* Select Options
Press space bar when on an item, to move it within the list. Cmd/Ctrl 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>
  <div class="slds-form-element__control">

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/Ctrl 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>
    <div class="slds-form-element__icon">

Required With Tooltip#

* Select Options
Press space bar when on an item, to move it within the list. Cmd/Ctrl 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">
      <abbr class="slds-required" title="required">* </abbr>Select Options</span>

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>
    <div class="slds-form-element__control">

Overview of CSS Classes#

Selector.slds-dueling-list
Summary

Initializes a dueling picklist

Supportdev-ready
Restrictdiv
VariantTrue
Selector.slds-dueling-list__column
Summary

Handles the layout of the dueling picklist

Restrict.slds-dueling-list div
Selector.slds-dueling-list__column_responsive
Summary

Changes the layout of the dueling picklist to be responsive

Restrict.slds-dueling-list__column
Selector.slds-dueling-list__options
Summary

Bounding visual container for listbox of options

Restrict.slds-dueling-list div
Selector.slds-listbox
Summary

Listbox container

Supportdev-ready
Restrict.slds-dropdown ul, .slds-dueling-list__options ul, .slds-pill_container ul, .slds-listbox_selection-group ul, .slds-combobox_container ul, .slds-form-element__control ul, .slds-popover__body ul
VariantTrue
Selector.slds-listbox_inline
Summary

Inline listbox

Restrict.slds-listbox
ModifierTrue
Selector.slds-listbox_horizontal
Summary

Horizontal listbox

Restrict.slds-listbox
ModifierTrue
Selector.slds-listbox__item
Summary

Listbox item

Restrict.slds-listbox > li
Selector.slds-listbox__option
Summary

Choosable option within listbox

Restrict.slds-listbox__item > div
Selector.slds-listbox__option-header
Summary

Header for choosable option within listbox

Restrict.slds-listbox__option h3
Selector.slds-listbox__option-icon
Summary

Container for listbox option icon

Restrict.slds-listbox__option span
Selector.slds-has-focus
Summary

Focus state of a vertical listbox option

Restrict.slds-listbox__option
ModifierTrue
Selector.slds-listbox__option_entity
Summary

Modifies the listbox option if it contains an entity object

Restrict.slds-listbox__option
Selector.slds-listbox__option_plain
Summary

Modifies the listbox option if it contains an plain object or string

Restrict.slds-listbox__option
Selector.slds-listbox__option_has-meta
Summary

If the listbox option has metadata or secondary information that sits below its primary text

Restrict.slds-listbox__option
Selector.slds-is-selected
Summary

Modifier that makes selected icon visible

Restrict.slds-listbox__option
ModifierTrue
Selector.slds-listbox__option-text_entity
Summary

The main text of an entity listbox

Restrict.slds-listbox__option span
Selector.slds-listbox__option-meta
Summary

The metadata or secondary text of an entity listbox

Restrict.slds-listbox__option span
Selector.slds-listbox__icon-selected
Summary

The icon within a plain listbox that indicates if an option has been selected or not.

Restrict.slds-listbox__item svg
Selector.slds-listbox_vertical
Summary

Creates a vertical listbox

Restrict.slds-listbox
ModifierTrue
Selector.slds-dropdown_length-5
Summary

Forces overflow scrolling after 5 list items

Restrict.slds-dropdown, .slds-dropdown__list, .slds-listbox
ModifierTrue
Selector.slds-dropdown_length-7
Summary

Forces overflow scrolling after 7 list items

Restrict.slds-dropdown, .slds-dropdown__list, .slds-listbox
ModifierTrue
Selector.slds-dropdown_length-10
Summary

Forces overflow scrolling after 10 list items

Restrict.slds-dropdown, .slds-dropdown__list, .slds-listbox
ModifierTrue
Selector.slds-dropdown_length-with-icon-5
Summary

Forces overflow scrolling after 5 list items with an icon

Restrict.slds-dropdown, .slds-dropdown__list, .slds-listbox
ModifierTrue
Selector.slds-dropdown_length-with-icon-7
Summary

Forces overflow scrolling after 7 list items with an icon

Restrict.slds-dropdown, .slds-dropdown__list, .slds-listbox
ModifierTrue
Selector.slds-dropdown_length-with-icon-10
Summary

Forces overflow scrolling after 10 list items with an icon

Restrict.slds-dropdown, .slds-dropdown__list, .slds-listbox
ModifierTrue
Selector.slds-is-selected
Summary

Selected/dragging state of a listbox option

Restrict.slds-dueling-list__options div
Selector.slds-is-grabbed
Summary

grabbed state of a listbox option

Restrict.slds-dueling-list__options div
Selector.slds-is-disabled
Summary

Disabled state of a picklist option

Restrict.slds-dueling-list__options

Dueling Picklist Release Notes

2.15.0

Added

  • Responsive variant now grows to use up the available horizontal space.

2.13.1

Fixed

  • Keyboard interaction examples were only showing Mac-specific instructions (Cmd), changed to be more general (Cmd/Ctrl)

2.10.0

Fixed

  • Locked items now have aria-disabled="true" to improve accessibility and help indicate the locked item's immutable behavior within the listbox.
  • Styling of locked items now inherits from .slds-listbox__option[aria-disabled="true"] and properly displays a disabled styling
  • Removed .slds-icon-text-default from .slds-icon and replaced it with .slds-current-color on the icon's container .slds-icon_container so the icon's color matches the locked item's disabled color
  • Removed draggable attribute from locked items as they are not draggable in the locked state

2.9.0

Fixed

  • Scrollbar not visible in narrow width containers
    • slds-dueling-list__options is no longer set to a fixed max-width and instead is limited to 100%

2.7.0

Changed

  • Wrapped slds-dueling-list element with slds-form-element__control.
  • Removed slds-text-title_caps from label.