Dual Listbox
The Avonni Dual Listbox displays two side-by-side lists, allowing users to select and transfer multiple items between them using interactive controls. Use it when you need users to explicitly pick items from a source pool and build an ordered selection.
Overview
The Dual Listbox lets users move items from a source (available) list into a selected list using add/remove buttons or drag-and-drop. It supports search filtering on the source list, reordering of selected items, required-item locking, and configurable validation rules (minimum/maximum selections).
Configuration
To configure the Dual Listbox, select it on the canvas. The Edit Dual Listbox panel opens on the right with three tabs: Properties, Interactions, and Style. The sections below mirror the Properties tab.
Data Source
Before building your Dual Listbox, connect it to a data source that supplies the available options. You have several choices depending on where your data lives:
Manual
Enter data directly into the component configuration.
Variable
This is useful for data that changes based on user interactions or other component logic.
Query
This is the most common option for displaying Salesforce records.
Data Mapping
When using a Variable or Query data source, configure the Data Mappings section to tell the component which fields from your records to use as item labels and values.
Think of it as a translator: Data Mappings ensure the correct information from your Salesforce data appears in the listbox.
How It Works (Contact Example)
If you use a Query data source to retrieve Contact records, you need to tell the Dual Listbox which fields to display:
Label: The main text shown for each item. For a Contact, a good choice is often a combination of
FirstNameandLastName.Description/Subtitle: Use a formula to combine multiple values and display supplementary information.
Content
Label
The text label displayed above the entire Dual Listbox component. You can also add Field level help text — a tooltip that explains the purpose of the listbox to your users.
Value
The list of items pre-selected by default. Enter values as a semicolon-separated string (for example, itemA;itemB). Use Value Collection to supply pre-selected values as a collection variable instead.
Variant
Controls how the label is displayed relative to the listbox.
Standard (default)
Label appears above the component.
Label Hidden
Label is hidden — useful for compact layouts where context is clear.
Label Inline
Sets the value, but the label still renders above the component: the Dual Listbox occupies the full width of its container, so there is no room beside it.
Label Stacked
Label starts above the component and animates upward on interaction.
Size
Defines the width of both the source and selected listboxes. Options: Small, Medium, Large, and Responsive (default). Responsive adapts to the available container width.
Show Search
When enabled, a search box appears above the source listbox so users can quickly filter available options. Especially useful when there are many items to choose from.
Draggable
When enabled, users can drag and drop items directly between the source and selected lists in addition to using the add/remove buttons.
Required
When enabled, the user must move at least one item to the selected list before submitting the form.
Disabled
When enabled, the listbox is read-only and users cannot interact with it.
Disable Reordering
When enabled, the Up and Down reorder buttons are hidden, so users cannot change the order of selected items.
The settings below sit under Advanced Options, at the bottom of the Properties tab.
Required Items
A list of item values that are locked in the selected list and cannot be removed. Populate this with values from your data source items.
Max Visible Items
The number of rows visible in each listbox before a vertical scrollbar appears. Default is 5.
Min / Max
Min: The minimum number of items required in the selected list (default: 0).
Max: The maximum number of items allowed in the selected list. Leave blank for no limit.
Hide Bottom Divider
When enabled, hides the bottom border line below the component.
Buttons
Customize the appearance of the action buttons (Add, Remove, Up, Down) that sit between the two listboxes.
Variant
The visual style applied to all four action buttons. Default is Border. Options: Bare, Container, Brand, Border, Border Filled, Bare Inverse, Border Inverse.
Size
The size of the action buttons. Default is Medium. Options: Xx Small, X Small, Small, Medium, Large. Note: Xx Small is intended for the Container, Brand, Border, Border Filled, and Border Inverse variants; Large for Bare and Bare Inverse.
Button Labels and Icons
Customize the tooltip text and icon for each individual action button:
Add Button Label / Add button icon name
Remove Button Label / Remove Button Icon
Up Button Label / Up Button Icon
Down Button Label / Down Button Icon
Labels
Customize the text labels displayed above each listbox and the placeholder shown when no items are selected.
Source Label: Label shown above the available-items listbox.
Selected Label: Label shown above the selected-items listbox.
Selected Placeholder: Text displayed inside the selected listbox when it is empty.
Set Component Visibility
All components support conditional visibility — see Component Visibility.
Interactions
Interactions define what happens when users interact with the Dual Listbox. Configure them from the Interactions tab of the Edit Dual Listbox panel.
Change
Fires whenever the user moves items between the source and selected lists — adding, removing, or reordering. Use the selectedItem and selectedItems output variables to access the affected item(s), or value and valueCollection to work with the selected values directly.
Output Variables
The Dual Listbox exposes these output variables you can reference elsewhere on the page after the user interacts with it.
Item Selection
When a user moves items between the source and selected lists, these variables update with the current selection.
Selected Item
Object
The last item moved into the selected list — includes its label, value, and description.
Selected Items
Object Collection
All items currently in the selected list, each with its label, value, and description.
Selected Item sObject
Record (SObject)
The Salesforce record associated with the last selected item. Requires a Query or Variable data source.
Selected Items sObject
Record Collection (SObject[])
The Salesforce records for all items currently in the selected list. Requires a Query or Variable data source.
Example: When a user selects contacts in a Dual Listbox backed by a Contact query, use Selected Items sObject to pass the chosen Contact records to a downstream component or action.
Others
Number of Items
Number
The total number of items in the dual listbox.
Styling
Configure the Dual Listbox's appearance from the Style tab of the Edit Dual Listbox panel.
Controls the outer spacing around the component.
Top / Right / Bottom / Left: Adjust the space on each side.
Controls the inner spacing between the component's content and its border.
Top / Right / Bottom / Left: Adjust the inner spacing on each side.
Controls the component's dimensions.
Width / Height: Set fixed dimensions.
Min Width / Max Width / Min Height / Max Height: Constrain the size within bounds.
Overflow: Control how content that exceeds the bounds is handled.
Customizes the border surrounding the component.
Color / Size / Style / Radius: Set the border color, thickness, style, and corner rounding.
Styles the component's main label.
Color / Font Size / Font Style / Font Weight: Set the label color and typography.
Styles the two listbox containers and their labels.
Boxes Label: Color / Font Size / Font Style / Font Weight.
Boxes: Background Color; Border Color / Border Size / Border Style / Border Radius.
Styles the individual options within the listboxes.
Background Color / Background Color Hover / Background Color Selected: Set the option background in each state.
Text Color / Text Color Hover / Text Color Selected: Set the option text color in each state.
Border Color / Border Size / Border Style: Customize the option border.
Styles option group headings.
Background Color: Set the group heading background.
Label Color / Font Size / Font Style / Font Weight: Set the group heading typography.
Last updated
Was this helpful?