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.

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

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.