Dual Listbox

A lightning-dual-listbox 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.

Here's an example that creates a simple dual listbox with 8 options. Options 7, 2 and 3 are selected under the second listbox. Options 2 and 7 are required options.

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 disabled fields are 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 on the validity attribute, 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: message-when-range-overflow, message-when-range-underflow, and message-when-value-missing.

To programmatically display error messages on invalid fields, use the reportValidity() method. For custom validity error messages, display the message using setCustomValidity() and reportValidity(). For more information, see lightning-input.

lightning-dual-listbox implements the dueling picklist blueprint in the Salesforce Lightning Design System (SLDS).

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with SLDS 1. If you use component styling hooks, limit the components to SLDS 1 themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Dueling Picklist: Styling Hooks Overview for documentation on component-specific hooks for this component.

Use the variant attribute with one of these values to position the labels differently relative to the picklist field.

• standard is the default
• label-hidden hides the label visually but makes it available to assistive technology. If you provide a value for field-level-help, the tooltip icon is still displayed.
• label-inline aligns the label next to the picklist field
• label-stacked places the label above the picklist field

To apply additional styling, use the SLDS utility classes with the class attribute.

To customize the SLDS styles on the "Move selection to Selected" or "Move selection up" buttons, use SLDS styling hooks. For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

To retrieve the selected values, use the onchange handler.

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.

change

The event fired when an item is selected in the combobox.

The change event returns the following parameter.

The event properties are as follows.