> 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/dynamic-components/components/dual-listbox.md).

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

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manual</strong></td><td>Enter data directly into the component configuration.</td><td></td></tr><tr><td><strong>Variable</strong></td><td>This is useful for data that changes based on user interactions or other component logic.</td><td></td></tr><tr><td><strong>Query</strong></td><td>This is the most common option for displaying Salesforce records.</td><td></td></tr><tr><td><strong>Picklist</strong></td><td>Retrieve data dynamically from a standard or custom picklist field within Salesforce.</td><td><a href="/pages/NMTcHeq9UuKYUmBedI8t">/pages/NMTcHeq9UuKYUmBedI8t</a></td></tr></tbody></table>

### 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 `FirstName` and `LastName`.
* **Description/Subtitle:** Use a formula to combine multiple values and display supplementary information.

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

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

| Variant                | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| **Standard** (default) | Label appears above the component.                                   |
| **Label Hidden**       | Label is hidden — useful for compact layouts where context is clear. |
| **Label Inline**       | Label appears to the left of the component.                          |
| **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.

#### 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 only available for Container, Brand, Border, Border Filled, and Border Inverse variants; Large is only available for Bare and Bare Inverse variants.

#### Button Labels and Icons

Customize the tooltip text and icon for each individual action button:

* **Add Button Label / Add Button Icon**
* **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](/dynamic-components/core-concepts/component-visibility.md).

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.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 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.

| Output variable            | Type                           | What it returns                                                                                                        |
| -------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **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

| Output variable     | Type   | What it returns                                            |
| ------------------- | ------ | ---------------------------------------------------------- |
| **Number of Items** | Number | The total number of items available in the source listbox. |


---

# 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/dynamic-components/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.