lightning:dualListbox

A widget that provides an input listbox, accompanied with a listbox of selectable options. Order of selected options is saved. This component requires API version 41.0 and later.

A lightning:dualListbox component represents two side-by-side list boxes. 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 inherits styling from Dueling Picklist in the Lightning Design System.

Here's an example that creates a simple dual list box with 8 options. Options 7, 2 and 3 are selected under the "Second Category" list box. Options 2 and 7 are required options.

<aura:component>
    <aura:attribute name="listOptions" type="List" default="[]"/>
    <aura:attribute name="defaultOptions" type="List" default="[]"/>
    <aura:attribute name="requiredOptions" type="List" default="[]"/>
    <aura:handler name="init" value="{! this }" action="{! c.initialize }"/>
    <lightning:dualListbox aura:id="selectOptions" name="Select Options"  label= "Select Options" 
                           sourceLabel="Available Options" 
                           selectedLabel="Selected Options" 
                           options="{! v.listOptions }"
                           value="{! v.defaultOptions }"
                           requiredOptions="{! v.requiredOptions }"
                           onchange="{! c.handleChange }"/>
</aura:component>

Here's the client-side controller that loads the options and handles value changes.

/** Client-Side Controller **/
({
    initialize: function (component, event, helper) {
        var options = [
            { value: "1", label: "Option 1" },
            { value: "2", label: "Option 2" },
            { value: "3", label: "Option 3" },
            { value: "4", label: "Option 4" },
            { value: "5", label: "Option 5" },
            { value: "6", label: "Option 6" },
            { value: "7", label: "Option 7" },
            { value: "8", label: "Option 8" },
        ];
        var values = ["7", "2", "3"];
        var required = ["2", "7"];
        component.set("v.listOptions", options);
        component.set("v.defaultOptions", values);
        component.set("v.requiredOptions", required);
    },
    handleChange: function (cmp, event) {
        // Get the list of the "value" attribute on all the selected options
        var selectedOptionsList = event.getParam("value");
        alert("Options selected: '" + selectedOptionsList + "'");
    }
})

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.

Usage Considerations

To retrieve the selected values, use the onchange handler.

({
    onChange: function (cmp, event) {
    // Retrieve an array of the selected options
    var selectedOptionValue = event.getParam("value");
    }
})

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.

Accessibility

Use the following keyboard shortcuts to work with dual list boxes.

  • 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.

When focus is on options:

  • Up Arrow - Move selection to previous option.
  • Down Arrow - Move selection to next option.
  • Cmd/Ctrl+Up Arrow - Move focus to previous option.
  • Cmd/Ctrl+Down Arrow - Move focus to next option.
  • Ctrl+Space - Toggle selection of focused option.
  • Cmd/Ctrl+Right Arrow - Move selected options to right list box.
  • Cmd/Ctrl+Left Arrow - Move selected options to left list box.
  • Tab - Move focus to next element.

When focus is on a button:

  • Enter - Perform the operation associated with that button.

Methods

This component supports the following methods.

focus(): Sets focus on the element.

checkValidity(): Returns the valid property value (Boolean) on the ValidityState object to indicate whether the dual listbox has any validity errors.

setCustomValidity(message): Sets a custom error message to be displayed when the dual listbox value is submitted.
  • message (String): The string that describes the error. If message is an empty string, the error message is reset.

showHelpMessageIfInvalid(): Shows the help message if the form control is in an invalid state.

Attributes

Attribute Name Attribute type Description Required?
body Component[] The body of the component. In markup, this is everything in the body of the tag.
name String Specifies the name of an input element.
value Object Specifies the value of an input element.
variant String The variant changes the appearance of an input field. Accepted variants include standard and label-hidden. This value defaults to standard.
disabled Boolean Specifies that an input element should be disabled. This value defaults to false.
readonly Boolean Specifies that an input field is read-only. This value defaults to false.
required Boolean Specifies that an input field must be filled out before submitting the form. This value defaults to false.
validity Object Represents the validity states that an element can be in, with respect to constraint validation.
onchange Action The action triggered when a value attribute changes.
accesskey String Specifies a shortcut key to activate or focus an element.
tabindex Integer Specifies the tab order of an element (when the tab button is used for navigating).
onfocus Action The action triggered when the element receives focus.
onblur Action The action triggered when the element releases focus.
label String Label for the dual list box. Yes
sourceLabel String Label for source options list box. Yes
selectedLabel String Label for selected options list box. Yes
options Object[] A list of options that are available for selection. Each option has the following attributes: label and value. Yes
requiredOptions List A list of required options that cannot be removed from selected options list box. This list is populated with values from options attribute.
values List A list of default options that are included in the selected options list box. This list is populated with values from the options attribute.
min Integer Minimum number of options required in the selected options list box.
max Integer Maximum number of options required in the selected options list box.