Dual Listbox

A lightning:dualListbox component represents two side-by-side listboxes. Select one or more options in the list on the left. Move selected options to the list on the right. The order of the selected options is maintained and you can reorder options.

This component implements styling from Dueling Picklist in the Lightning Design System.

Here’s an example that creates a simple dual listbox with 8 options. Options 7, 2 and 3 are selected under the “Second Category” listbox. Options 2 and 7 are required options.

1<aura:component>
2
3  <aura:attribute name="listOptions" type="List" default="[]" />
4
5  <aura:attribute name="defaultOptions" type="List" default="[]" />
6
7  <aura:attribute name="requiredOptions" type="List" default="[]" />
8
9  <aura:handler name="init" value="{! this }" action="{! c.initialize }" />
10
11  <lightning:dualListbox
12    aura:id="selectOptions"
13    name="Select Options"
14    label="Select Options"
15    sourceLabel="Available Options"
16    selectedLabel="Selected Options"
17    options="{! v.listOptions }"
18    value="{! v.defaultOptions }"
19    requiredOptions="{! v.requiredOptions }"
20    onchange="{! c.handleChange }"
21  />
22
23</aura:component>

Here’s the client-side controller that loads the options and uses the onchange handler to handle value changes.

1/** Client-Side Controller **/
2({
3  initialize: function (component, event, helper) {
4    var options = [
5      { value: "1", label: "Option 1" },
6      { value: "2", label: "Option 2" },
7      { value: "3", label: "Option 3" },
8      { value: "4", label: "Option 4" },
9      { value: "5", label: "Option 5" },
10      { value: "6", label: "Option 6" },
11      { value: "7", label: "Option 7" },
12      { value: "8", label: "Option 8" },
13    ];
14    var values = ["7", "2", "3"];
15    var required = ["2", "7"];
16    component.set("v.listOptions", options);
17    component.set("v.defaultOptions", values);
18    component.set("v.requiredOptions", required);
19  },
20  handleChange: function (cmp, event) {
21    // Get the list of the "value" attribute on all the selected options
22    var selectedOptionsList = event.getParam("value");
23    alert("Options selected: '" + selectedOptionsList + "'");
24  },
25});

To specify the number of options users can select, use the min and max attributes. For example, if you set min to 3 and max to 8, users must select at least 3 options and at most 8 options.

Client-side input validation is available for this component. Note that a disabled dual listbox is always valid.

To check the validity states of the input, use the validity attribute to return an object with read-only boolean attributes.

• rangeOverflow
• rangeUnderflow
• valueMissing
• valid

For more information, see lightning:input.

When an input validation fails, the following messages are displayed by default.

• rangeOverflow: Select at most [max] options
• rangeUnderflow: At least [min] options must be selected
• valueMissing: An option must be selected

[max] and [min] refer to the numerical values for the max and min attributes you provide.

You can override the default messages by providing your own values for these attributes: messageWhenRangeOverflow, messageWhenRangeUnderflow, and messageWhenValueMissing

To programmatically display error messages on invalid fields, use the reportValidity() method. For custom validity error messages, display the message using setCustomValidity() and reportValidity().

To retrieve the selected values, use the onchange handler as shown in the previous example.

The onchange handler is triggered when you click the left and right buttons to move options from one list to another or when you change the order of options in the selected options list.

For optimal performance, limit each list to 50 options or fewer. Moving more than 50 options at once can be resource-intensive and may result in noticeable delays for users.

Use these keyboard shortcuts to work with dual listboxes.

• Click - Select a single option.
• Cmd+Click - Select multiple options or deselect selected options.
• Shift+Click - Select all options between the current and last clicked option.

To work with options, move focus to an option and use these shortcuts.

• Up Arrow - Move selection to previous option.
• Down Arrow - Move selection to next option.
• Ctrl+Up Arrow (Windows) or Cmd+Up Arrow (Mac) - Move focus to previous option.
• Ctrl+Down Arrow (Windows) or Cmd+Down Arrow (Mac) - Move focus to next option.
• Ctrl+Space - Toggle selection of focused option.
• Ctrl+Right Arrow (Windows) or Cmd+Right Arrow (Mac) - Move selected options to right listbox.
• Ctrl+Left Arrow (Windows) or Cmd+Left Arrow (Mac) - Move selected options to left listbox.
• Tab - Move focus to the buttons or between boxes.

When focus is on an option, type a character to move focus to the next option with a name that starts with the typed character. The first typed character is matched with the first character of the label in the order the options occur. To select the focused option, press Ctrl+Space. This type-ahead feature isn’t currently supported for multibyte characters such as Chinese and Japanese.

For example, if you have multiple options that starts with the letter “E” and focus is on an option that starts with “A”, type “E” to move focus to the first option that starts with “E”. Typing “E” again moves focus to the next option that starts with “E”.

The component presents two buttons to move an option to the selected list and back to the source list.

• The first button’s assistive text is “Move selection to Selected”, where Selected is the label of the second list.
• The second button’s assistive text is “Move selection to Source”, where Source is the label of the first list.

When focus is on a button:

• Move selection to Selected - Select an option from the first (source) list, then press Enter on the button to move the option to the selected list.
• Move selection to Source - Select an option from the second (selected) list, then press Enter on the button to move the option back to the source list.

If no items are selected or available, the move buttons and reorder buttons are disabled.

To accommodate high magnification when zoom is greater than 200%, the list boxes stack vertically, separated by up and down arrow icons instead of right and left arrow buttons.