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.
When focus is on options:
When focus is on a 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.
showHelpMessageIfInvalid(): Shows the help message if the form control is in an invalid state.
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. |