Comment on page

Dual Listbox

Used to move options between two lists and is often referred to as a multi-select.

Overview
The Dual Listbox component allows users to select multiple items from two lists. It is typically made up of two lists of items, each with a set of options that the user can choose from. Users can select items from either list by clicking on them and move items between them using arrow buttons or drag-and-drop functionality.
The Dual Listbox component may also include filtering and searching options, allowing users to quickly find specific items within the lists. It may also include formatting options for the displayed items, such as font size and color.
Changing the Properties
Choosing a variant
If you want to add a label to your dual listbox, you can change to variant to access multiple settings.
Setting a size
Width of the source options listbox and the selected options listbox. Valid values include small, medium and large
Adding a search engine
If present, a search box is added to the first listbox to search options. Useful if you are displaying a lot of options.
Make options draggable
If present, the options are draggable between the left and right lists.
Adding Interactions
Interactions define what will happen when users select an option. You can find a list of interactions available here.
Styling the Dual Listbox
From the Styles panel, you can customize styling for the Dual Listbox: Margin, Header, Option, Boxes Label and Boxes.  
You can find the instructions for styling here.
Tutorials
Display contacts with custom icons
​
​
Accounts list group by industry
​
​
Specifications
Attributes
Name
Type
Description
addButtonIconName
String
Name of the add button icon, in the format 'utility:right".
addButtonLabel
String
Label of the add button.
allowSearch
Boolean
If present, a search box is added to the first listbox.
buttonSize
String
For the bare variant, valid values include x-small, small, medium, and large. For non-bare variants, valid values include xx-small, x-small, small, and medium.
buttonVariant
String
Use this variant for all button icons (add, up, down and remove). Valid values include bare, container, brand, border, border-filled, bare-inverse and border-inverse.
disableReordering
Boolean
If present, the Up and Down buttons used for reordering are hidden.
disabled
Boolean
If present, the listbox is disabled and users cannot interact with it.
downButtonIconName
String
Name of the down button icon to be used in the format ‘utility:down’.
downButtonLabel
String
Label of the down button.
draggable
Boolean
If present, the options are draggable.
fieldLevelHelp
String
Help text detailing the purpose and function of the dual listbox.
hideBottomDivider
Boolean
If present, hides the bottom divider.
label
String
Label of the dual listbox.
max
Integer
Maximum number of options allowed in the selected options listbox.
maxVisibleOptions
Integer
Number of options displayed in the listboxes before vertical scrollbars are displayed. Determines the height of the listbox.
min
Integer
Minimum number of options required in the selected options listbox.
removeButtonIconName
String
Name of the remove button icon in the format ‘utility:left’.
removeButtonLabel
String
Label of the remove button.
required
Boolean
If present, the user must add an item to the selected listbox before submitting the form.
selectedLabel
String
Label of the Selected options list.
selectedPlaceholder
String
Text displayed when no options are selected.
size
String
Width of the source options listbox and the selected options listbox. Valid values include small, medium and large.
sourceLabel
String
Label of the Source options list.
upButtonIconName
String
Name of the up button icon to be used in the format ‘utility:up'.
upButtonLabel
String
Label of the up button.
value
String[]
A list of default options that are included in the selected options listbox. This list is populated with values from the options attribute.
valueSemiColonSeparated
String
​
variant
String
The variant changes the appearance of the dual listbox. Valid variants include standard, label-hidden and label-stacked. Use label-hidden to hide the label but make it available to assistive technology. Use label-stacked to place the label above the dual listbox.
requiredOptions
String[]
​
options
DualListboxOption[]
Items that are available for selection.
picklistFieldApiName
String
List of objects available with a picklist field.
picklistSortOrder
String
Sort order of the picklist values.
Events
Name
Description
change
The event fired when one or several options are moved from one box to the other.
Styling Hooks
Header
Name
Description
Text Color
Define a text color for the label text.
Font Size
Define a font size for the label text.
Font Style
Define a font style for the label text.
Font Weight
Define a font weight for the label text.
Option
Name
Description
Text Color
Define a text color for the option.
Text Color Hover
Define a text color hover for the option.
Text Color Selected
Define a text color selected for the option.
Background Color
Define a background color for the option.
Background Color Hover
Define a background color hover for the option.
Background Color Selected
Define a background color selected for the option.
Border Color
Define a border color for the option.
Border Size
Define a border size for the option.
Border Style
Define a border style for the option.
Boxes Label
Name
Description
Text Color
Define a text color for boxes label.
Font Size
Define a font size for boxes label.
Font Style
Define a font style for boxes label.
Font Weight
Define a font weight for boxes label.
Boxes
Name
Description
Border Color
Define a border color for boxes.
Border Size
Define a border size for boxes.
Border Style
Define a border style for boxes.

Name	Type	Description
addButtonIconName	String	Name of the add button icon, in the format 'utility:right".
addButtonLabel	String	Label of the add button.
allowSearch	Boolean	If present, a search box is added to the first listbox.
buttonSize	String	For the bare variant, valid values include x-small, small, medium, and large. For non-bare variants, valid values include xx-small, x-small, small, and medium.
buttonVariant	String	Use this variant for all button icons (add, up, down and remove). Valid values include bare, container, brand, border, border-filled, bare-inverse and border-inverse.
disableReordering	Boolean	If present, the Up and Down buttons used for reordering are hidden.
disabled	Boolean	If present, the listbox is disabled and users cannot interact with it.
downButtonIconName	String	Name of the down button icon to be used in the format ‘utility:down’.
downButtonLabel	String	Label of the down button.
draggable	Boolean	If present, the options are draggable.
fieldLevelHelp	String	Help text detailing the purpose and function of the dual listbox.
hideBottomDivider	Boolean	If present, hides the bottom divider.
label	String	Label of the dual listbox.
max	Integer	Maximum number of options allowed in the selected options listbox.
maxVisibleOptions	Integer	Number of options displayed in the listboxes before vertical scrollbars are displayed. Determines the height of the listbox.
min	Integer	Minimum number of options required in the selected options listbox.
removeButtonIconName	String	Name of the remove button icon in the format ‘utility:left’.
removeButtonLabel	String	Label of the remove button.
required	Boolean	If present, the user must add an item to the selected listbox before submitting the form.
selectedLabel	String	Label of the Selected options list.
selectedPlaceholder	String	Text displayed when no options are selected.
size	String	Width of the source options listbox and the selected options listbox. Valid values include small, medium and large.
sourceLabel	String	Label of the Source options list.
upButtonIconName	String	Name of the up button icon to be used in the format ‘utility:up'.
upButtonLabel	String	Label of the up button.
value	String[]	A list of default options that are included in the selected options listbox. This list is populated with values from the options attribute.
valueSemiColonSeparated	String
variant	String	The variant changes the appearance of the dual listbox. Valid variants include standard, label-hidden and label-stacked. Use label-hidden to hide the label but make it available to assistive technology. Use label-stacked to place the label above the dual listbox.
requiredOptions	String[]
options	DualListboxOption[]	Items that are available for selection.
picklistFieldApiName	String	List of objects available with a picklist field.
picklistSortOrder	String	Sort order of the picklist values.

Name	Description
change	The event fired when one or several options are moved from one box to the other.

Name	Description
Text Color	Define a text color for the label text.
Font Size	Define a font size for the label text.
Font Style	Define a font style for the label text.
Font Weight	Define a font weight for the label text.

Name	Description
Text Color	Define a text color for the option.
Text Color Hover	Define a text color hover for the option.
Text Color Selected	Define a text color selected for the option.
Background Color	Define a background color for the option.
Background Color Hover	Define a background color hover for the option.
Background Color Selected	Define a background color selected for the option.
Border Color	Define a border color for the option.
Border Size	Define a border size for the option.
Border Style	Define a border style for the option.

Name	Description
Text Color	Define a text color for boxes label.
Font Size	Define a font size for boxes label.
Font Style	Define a font style for boxes label.
Font Weight	Define a font weight for boxes label.

Name	Description
Border Color	Define a border color for boxes.
Border Size	Define a border size for boxes.
Border Style	Define a border style for boxes.

Last modified 6mo ago