--- schema_version: "1" id: 9c9b2014170b7b53c99c0245c21e7c448a1356a65922880c0125571e0fcf056c title: Dual Listbox collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/dualListbox/lightning-dual-listbox.md canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-dual-listbox.html source_site: developer.salesforce.com content_type: documentation content_hash: 834835dd4299e14ab9e62a2f3852aa36d2602d8c02671a61136fb0896886fd16 products: - Lightning Component Reference --- # Dual Listbox **`lightning-dual-listbox`** A pair of listboxes that enables multiple options to be selected and reordered. **For Use In** Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline ::::::tabset{tabs='["Example", "Develop", "Specifications"]'} :::::tab ::component-playground{component="dualListbox" model="lwc" namespace="lightning"} ::::: :::::tab A `lightning-dual-listbox` component represents two side-by-side listboxes. Select one or more options in the list on the left. Move the selected options to the list on the right. The order of the selected options persists 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. ```html ``` ```javascript import { LightningElement } from "lwc"; export default class MyComponentName extends LightningElement { listOptions = [ { 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" }, ]; defaultOptions = ["7", "2", "3"]; requiredOptions = ["2", "7"]; handleChange(event) { // Get the list of the "value" attribute on all the selected options const selectedOptionsList = event.detail.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. ## Design `lightning-dual-listbox` implements the dueling picklist blueprint in the Salesforce Lightning Design System (SLDS). The dueling picklist adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use. | | SLDS 1 | SLDS 2 | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | | **Design** | [Dueling Picklist](https://v1.lightningdesignsystem.com/components/dueling-picklist/) | [Data Tables](https://www.lightningdesignsystem.com/components/dueling-picklist/) | | **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) | ## Input Validation Client-side input validation is available for this component. 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](/docs/platform/lightning-component-reference/guide/lightning-input.html). ## Error Messages When an input validation fails, the following messages are shown 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`. ## Custom Validity Error Messages To programmatically show error messages on invalid fields, use the `reportValidity()` method. For custom error messages, return the message by using `setCustomValidity()` and `reportValidity()`. For more information, see [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html). ## Component Styling Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks. For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide. ### Variants 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 shown. - `label-inline` aligns the label next to the picklist field - `label-stacked` places the label above the picklist field ### Customize Component Styling To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) 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](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide. ## Usage Considerations To return the selected values, use the `onchange` handler. ```javascript handleChange(event) { // Get an array of the selected options const selectedOptionsList = event.detail.value; alert(`Options selected: ${selectedOptionsList}`); } ``` 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 can result in noticeable delays for users. ## Accessibility 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 the previous option. - Ctrl+Down Arrow (Windows) or Cmd+Down Arrow (Mac) - Move focus to the next option. - Ctrl+Space - Toggle selection of focused option. - Ctrl+Right Arrow (Windows) or Cmd+Right Arrow (Mac) - Move selected options to the right listbox. - Ctrl+Left Arrow (Windows) or Cmd+Left Arrow (Mac) - Move selected options to the 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 that 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 start 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. ## Custom Events **`change`** The event fired when an item is selected in the combobox. The `change` event returns this parameter. | Parameter | Type | Description | | --------- | ------ | ----------------------------------------- | | value | string | A comma-separated list of selected items. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | true | This event bubbles up through the DOM. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | true | This event propagates outside of the component in which it was dispatched. | ::::: :::::tab ::component-specification{component="dualListbox" model="lwc" namespace="lightning"} ::::: ::::::