> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/flow/flow-components/dual-listbox.md).

# Dual Listbox

***

## Tutorials

#### Getting Started

<figure><img src="/files/tVp3T5Sa2lgUGnNeqYqA" alt=""><figcaption></figcaption></figure>

[**Display Contacts with Custom Icons**](/flow/tutorials/components/dual-listbox/display-contacts-with-custom-icons.md)

***

<figure><img src="/files/4dNytXJn7vlSmGzR7KMb" alt=""><figcaption></figcaption></figure>

[**Accounts List Grouped by Industry**](/flow/tutorials/components/dual-listbox/accounts-list-group-by-industry.md)

***

## 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**](/flow/component-builder/data-sources/manual.md)     | Static lists that rarely change      | You type each value directly in the Component Builder                           |
| [**Variable**](/flow/component-builder/data-sources/variable.md) | Dynamic data from Salesforce records | Connect a flow collection variable from a **Get Records** element               |
| [**Picklist**](/flow/component-builder/data-sources/picklist.md) | Salesforce picklist fields           | Pull options from an existing picklist field on any object                      |
| [**Query**](/flow/component-builder/data-sources/query.md)       | 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.

{% hint style="info" %}
**Example**

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

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.

{% hint style="info" %}
**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.
{% endhint %}

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.

{% hint style="info" %}
**Example**

An opportunity qualification flow where users select relevant industries from the `Industry` picklist on Account.
{% endhint %}

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.

{% hint style="info" %}
**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.
{% endhint %}

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)

{% hint style="success" %}
**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
{% endhint %}

### 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

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

{% hint style="info" %}
**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
{% endhint %}

#### 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.

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

{% hint style="info" %}
**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
{% endhint %}

#### Level Mapping

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

{% hint style="info" %}
**Example**

Map **Level** to a custom `Hierarchy_Level__c` field to display a department org chart where sub-departments are indented under their parent
{% endhint %}

### 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:

<table><thead><tr><th width="109.53125">Size</th><th>When to use</th></tr></thead><tbody><tr><td><strong>Small</strong></td><td>Short item labels, tight layouts</td></tr><tr><td><strong>Medium</strong></td><td>Most use cases — default</td></tr><tr><td><strong>Large</strong></td><td>Long item labels or when the Dual Listbox is the main component on the screen</td></tr><tr><td><strong>Responsive</strong></td><td>Adapts width to the available container space</td></tr></tbody></table>

**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`

<figure><img src="/files/Qndmk8coC8mUS9mRiv5z" alt=""><figcaption></figcaption></figure>

#### 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.

{% hint style="warning" %}
**Important**

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

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.

{% hint style="warning" %}
**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.
{% endhint %}

<figure><img src="/files/Zt4RrZCsbIkyQ14n1QUQ" alt=""><figcaption></figcaption></figure>

### Buttons

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

<table><thead><tr><th width="253.4921875">Setting</th><th>What it controls</th></tr></thead><tbody><tr><td><strong>Button Variant</strong></td><td>Visual style applied to all action buttons</td></tr><tr><td><strong>Button Size</strong></td><td>Size of the transfer buttons — Xx Small, X Small, Small, Medium, Large</td></tr><tr><td><strong>Add Button Label</strong></td><td>Tooltip for the "move right" button</td></tr><tr><td><strong>Add Button Icon Name</strong></td><td>Icon for the add button</td></tr><tr><td><strong>Remove Button Label</strong></td><td>Tooltip for the "move left" button</td></tr><tr><td><strong>Remove Button Icon Name</strong></td><td>Icon for the remove button</td></tr><tr><td><strong>Up Button Label</strong></td><td>Tooltip for the up-arrow reorder button</td></tr><tr><td><strong>Up Button Icon Name</strong></td><td>Icon for the up-arrow button</td></tr><tr><td><strong>Down Button Label</strong></td><td>Tooltip for the down-arrow reorder button</td></tr><tr><td><strong>Down Button Icon Name</strong></td><td>Icon for the down-arrow button</td></tr></tbody></table>

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

### Labels

<table><thead><tr><th width="196.19921875">Setting</th><th>What it controls</th></tr></thead><tbody><tr><td><strong>Source Label</strong></td><td>Header text above the source (left) list — default is "Source"</td></tr><tr><td><strong>Selected Label</strong></td><td>Header text above the selected (right) list — default is "Selected"</td></tr><tr><td><strong>Selected Placeholder</strong></td><td>Text shown in the selected list when it's empty</td></tr></tbody></table>

> **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](/flow/component-builder/interactions-panel.md) 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.

{% tabs %}
{% tab title="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.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing between the component's content and its border.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Size" %}
Controls the component's dimensions.

* **Width / Height:** Set fixed dimensions for the component.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
* **Overflow:** Control how content that exceeds the bounds is handled.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the component.

* **Color:** Set the border color.
* **Size:** Adjust the border thickness.
* **Style:** Choose a border style (e.g. solid, dashed, dotted).
* **Radius:** Control the roundness of the corners.
  {% endtab %}

{% tab title="Label" %}
Styles the main field label above the listboxes.

* **Color:** Set the label text color.
* **Font Size / Font Style / Font Weight:** Control the label typography.
  {% endtab %}

{% tab title="Boxes Label" %}
Styles the source and selected labels that sit above each listbox.

* **Color:** Set the boxes label text color.
* **Font Size / Font Style / Font Weight:** Control the boxes label typography.
  {% endtab %}

{% tab title="Boxes" %}
Styles the listbox containers that hold the options.

* **Background Color:** Set the listbox background.
* **Border Color / Border Size / Border Style / Border Radius:** Customize the listbox borders.
  {% endtab %}

{% tab title="Option" %}
Styles the individual options inside the listboxes, including their hover and selected states.

* **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 borders.
  {% endtab %}

{% tab title="Groups" %}
Styles option group headings within the listboxes.

* **Background Color:** Set the group background.
* **Label Color:** Set the group label text color.
* **Font Size / Font Style / Font Weight:** Control the group label typography.
  {% endtab %}
  {% endtabs %}

## 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](/flow/component-builder/interactions-panel/open-flow-dialog.md) or [Open Flow Panel](/flow/component-builder/interactions-panel/open-flow-panel.md) interaction can fill with values from a launched flow. See [Flow Interaction Output Variables](/flow/component-builder/interactions-panel/flow-interaction-output-variables.md).

## 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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/flow/flow-components/dual-listbox.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.