Dual Listbox

The Dual Listbox provides two side-by-side lists, allowing users to select and transfer multiple items between them using interactive controls

---

Tutorials

Getting Started

Display Contacts with Custom Icons

---

Accounts List Grouped by Industry

---

Overview

The Dual Listbox places two lists side by side — a source list of available options and a selected list. Users move items between them using transfer buttons (or drag-and-drop). It supports search, reordering within the selected list, validation rules, and fully customizable button labels, making it the right choice for any "pick from a larger set" use case in a Salesforce Flow.

Configuration

To configure it, click the component on the Flow screen. The Edit Dual Listbox Component panel opens on the right with three tabs: Properties, Interactions, and Style. The sections below mirror the Properties tab.

Data Source

The data source controls where the Dual Listbox gets its items.

Data Source	Best For	How It Works
Manual	Static lists that rarely change	You type each value directly in the Component Builder
Variable	Dynamic data from Salesforce records	Connect a flow collection variable from a Get Records element
Picklist	Salesforce picklist fields	Pull options from an existing picklist field on any object
Query	Large or complex datasets	Fetch records directly from a Salesforce object — no Get Records element needed

Manual — Use When…

You have a short, fixed list of options that won't change between flow runs.

Example

A preference form where users pick communication channels from a fixed set: Email, Phone, SMS, Mail.

In the Component Builder, click Add Item to enter each value one by one. Set a Label (what the user sees) and a Value (what the flow stores).

Variable — Use When…

Your list items come from Salesforce records and may change over time.

Example

A case reassignment flow where the source list shows all active support agents from a Get Records element, and the user selects which agents to assign.

1. In your flow, add a Get Records element to fetch the records you need (e.g., all active Users where Profile.Name = "Support Agent")
2. In the Component Builder, set the data source to Variable
3. Map the flow collection variable to the Dual Listbox

Picklist — Use When…

You want to display the values of an existing Salesforce picklist field.

Example

An opportunity qualification flow where users select relevant industries from the Industry picklist on Account.

1. In the Component Builder, set the data source to Picklist
2. Choose the Salesforce object and picklist field

Query — Use When…

You need records from Salesforce, but don't want to add a separate Get Records element to your flow.

Example

A territory assignment flow where the source list shows all Accounts in a specific region. The query pulls Account records where BillingState = "California" directly.

1. In the Component Builder, set the data source to Query
2. Select the Salesforce object (e.g., Account)
3. Add filters to narrow the results (click Add Condition or Add Scope)
4. Set Order By to control the sort order of items in the source list
5. Set the maximum number of Records to limit the number of items loaded. Don't put anything if you want to load all the data.
6. Map the fields to display (see Data Mappings)

Tip

Query simplifies your flow by removing the need for a separate Get Records element. For most "pick from a list of records" use cases, start here

Data Mapping

Once your data source is set up, map Salesforce fields to the Dual Listbox attributes so that items display correctly. In the Properties tab, open Data Mappings.

Core Mappings

Mapping	What it controls
Label	The primary text users see for each item (e.g., Name, Subject)
Value	The unique identifier stored when an item is selected (e.g., Id)
Description	Secondary text shown below the label — supports merge field syntax (e.g., {{{BillingCity}}} - {{{Industry}}})
Group Name	Groups items under a shared heading in the source list (e.g., map to Industry to group accounts by industry)

Example

For a list of Accounts, map Label to Name, Value to Id, Description to {{{BillingCity}}}, and Group Name to Industry. Users see accounts organized by industry, each showing the city underneath the name

Avatar Mappings

Each item can display an avatar (icon or image) next to its label. Configure these in the Avatar sub-section of Data Mappings.

Mapping	What it controls
Avatar	Shape of the avatar container — Square or Circle
Icon Name	A Salesforce Lightning icon to display (e.g., standard:account, utility:user)
Icon Source	Field to pull the icon name from dynamically
Icon Size	Size of the icon — Small, Medium, or Large
Image Source	Field containing an image URL to use as the avatar (e.g., a Contact photo URL)
Title	Tooltip text shown on hover over the avatar
Position	Where the avatar appears relative to the option text — Options Left or Options Right

Example

In a contact selection list, map Image Source to SmallPhotoUrl and set Avatar to Circle to show each contact's profile photo next to their name

Level Mapping

Mapping	What it controls
Level	Indentation level for hierarchical display — use a numeric field to create a visual tree structure

Example

Map Level to a custom Hierarchy_Level__c field to display a department org chart where sub-departments are indented under their parent

Properties

Label — component label displayed above the Dual Listbox.

Field Hint Text — helper text displayed below the component to guide the user.

Variant — controls the label display: Standard, Label Hidden, Label Inline, or Label Stacked.

Size — defines the width of the source and selected listboxes:

Size	When to use
Small	Short item labels, tight layouts
Medium	Most use cases — default
Large	Long item labels or when the Dual Listbox is the main component on the screen
Responsive	Adapts width to the available container space

Show Search — adds a search box above the source list so users can quickly filter options.

Draggable — enables drag-and-drop between and within listboxes.

Required — the flow won't advance until at least one item is selected.

Disabled — grays out the component so users can see options but cannot move items.

Initial Selected Values — items to pre-load in the "Selected" list when the screen loads.

Setting Default Selected Values — Manual Data Source

Click the Add Item button next to the Initial Selected Values field. Each click adds one item. Enter the Value attribute of the item — not the Label the user sees.

Example: You created three manual items:

Label	Value
Standard Support	standardSupport
Premium Support	preniumSupport
Basic Training	basicTraining

To pre-select "Standard Support" and "Basic Training":

1. Click Add Item and enter standardSupport
2. Click Add Item again and enter basicTraining

Setting Default Selected Values — Variable, Query, or Picklist

Map the Initial Selected Values field to a flow collection variable that contains the values you want pre-selected.

Important

The variable must be a collection variable (not a single-value text variable). Only collection variables appear in the list of available mappings

The collection should contain the values that match the Value field in your Data Mappings (typically the record Id).

Example: A renewal flow needs to pre-select the customer's current subscriptions. Before the screen element:

1. Add a Get Records element to fetch the customer's active Subscription records
2. Use an Assignment element to store their Id values in a text collection variable {!currentSubscriptionIds}
3. On the Dual Listbox, click the icon next to Initial Selected Values, select Mapped, and choose {!currentSubscriptionIds}

When the screen loads, those subscriptions appear in the "Selected" list automatically.

Important

Each value in the collection must exactly match what's in the Value attribute of your data source items. A mismatch (extra space, wrong casing, wrong field) means the item won't appear as pre-selected — it stays in the source list with no error.

Buttons

The Buttons section lets you customize the transfer controls between the two lists.

Setting	What it controls
Button Variant	Visual style applied to all action buttons
Button Size	Size of the transfer buttons — Xx Small, X Small, Small, Medium, Large
Add Button Label	Tooltip for the "move right" button
Add Button Icon Name	Icon for the add button
Remove Button Label	Tooltip for the "move left" button
Remove Button Icon Name	Icon for the remove button
Up Button Label	Tooltip for the up-arrow reorder button
Up Button Icon Name	Icon for the up-arrow button
Down Button Label	Tooltip for the down-arrow reorder button
Down Button Icon Name	Icon for the down-arrow button

Example: In a French-language flow, change Add Button Label to "Ajouter" and Remove Button Label to "Retirer" to localize the interface.

Labels

Setting	What it controls
Source Label	Header text above the source (left) list — default is "Source"
Selected Label	Header text above the selected (right) list — default is "Selected"
Selected Placeholder	Text shown in the selected list when it's empty

Example: For a team assignment flow, set Source Label to "Available Agents" and Selected Label to "Assigned Agents" so users immediately understand the context.

Advanced Options

Disable Reordering — when enabled, hides the Up and Down buttons so users cannot reorder items in the selected list.

Required Options — a list of item values that must always remain selected and cannot be removed by the user.

Max Visible Options — the maximum number of visible rows in each listbox before a scrollbar appears (default: 5).

Minimum — the minimum number of items required in the selected list before the flow can proceed.

Maximum — the maximum number of items allowed in the selected list.

Hide Bottom Divider — hides the bottom border beneath the component.

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 when the user moves items between the source and selected lists. Use this to navigate automatically, show a confirmation toast, update a dependent component, or store the selection in a flow variable.

Styling

The Style tab gives you fine-grained control over the Dual Listbox's appearance. Configure it from the Style tab of the Edit Dual Listbox panel.

Margin

Controls the outer spacing around the component, creating space between it and other elements on the screen.

• Top / Right / Bottom / Left: Adjust the space on each side of the component.

Padding

Size

Border

Label

Boxes Label

Boxes

Option

Groups

Output Variables

The Dual Listbox exposes these output variables you can reference in your flow after the screen. To use them, select the screen element in Flow Builder, then the Dual Listbox component, and pick the output variable you need.

Item Selection

Updated whenever the user moves items between the source and selected lists.

Output variable	Type	What it returns
Value	Text Collection	The values of all items currently in the selected list, in display order.
Selected Option	Record (SObject)	The last item the user moved to the selected list.
Selected Options	Collection of Records (SObject)	All items currently in the selected list as full records, preserving their original field data.

Example: After a case reassignment screen, store Value in a text collection variable {!assignedAgentIds} to pass the selected agent IDs to an Update Records element.

Others

Output variable	Type	What it returns
Number of Items	Integer	The total number of items in the dual listbox (source and selected combined).

Flow Interaction Output Variables

Like all interactive Flow components, the Dual Listbox exposes generic output slots (Variable 1–10) that an Open Flow Dialog or Open Flow Panel interaction can fill with values from a launched flow. See Flow Interaction Output Variables.

Troubleshooting Common Issues

• Items don't appear in the source list — Data source not configured or query/Get Records returns no results. Check your data source type: if using Variable, verify the Get Records element returns records; if using Query, check your filters.
• Selected items aren't saved to the flow — No On Change interaction is configured. Add an On Change interaction to store selected values in a flow variable.
• Duplicate items appear — The Value mapping points to a non-unique field. Map Value to a unique field like Id.
• Search box doesn't appear — Show Search is toggled off. Open the Properties tab and toggle on Show Search.
• Default selections don't appear — Values in Initial Selected Values don't match the Value mapping. Make sure the values exactly match the values from your data source — check for extra spaces or mismatched casing.
• Items can't be reordered — Disable Reordering is toggled on. Toggle off Disable Reordering in the Advanced Options.
• Component appears but is grayed out — Disabled is toggled on. Check the Disabled toggle — it may be mapped to a flow variable that evaluates to true.