> 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/combobox.md).

# Combobox

The Avonni Combobox component lets users pick one or more options from a dropdown list — sourced from manual entries, a query, a variable, or picklist values — with optional search, selection limits, validation messages, and custom actions inside the dropdown.

The component ships as two presets:

* **Combobox** — single selection.
* **Combobox Multiselect** — multiple selections, with the **Is Multi Select** setting turned on. This variant unlocks the selection-limit, validation-message, and keep-open settings described below.

Both presets are the same component; switching the **Is Multi Select** setting converts one into the other.

## Overview

To start with the Avonni Combobox component, you'll first connect it to your data, map the fields that make up each option, and then customize how the dropdown looks and behaves. The sections below follow the configuration panel from top to bottom, so you can read along as you build.

{% content-ref url="/spaces/dHOej9Pd5IxJNGEJMZKW/pages/9sEBLKlcd755E6HDFStc" %}
[User Activity Report](/projects/dynamic-components/working-with-data/user-activity-report.md)
{% endcontent-ref %}

## Configuration

To configure the Combobox, select it on the canvas. The **Edit Combobox** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

### Data Source

Before you build your combobox, you must tell the Avonni Combobox component where to get the options it should display. You have several options, depending on the source and nature of your data:

<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 dynamic data source (Query or Variable), you'll configure the **Data Mappings** section to tell the component how to turn each record into a combobox option. Map the fields from your data to the parts of each option:

* **Label**: The field containing the text shown for each option (for example, `Contact.Name` or a formula that combines fields).
* **Secondary Text**: The field containing the subtext shown below the label.
* **Disabled**: Controls whether the option is disabled and cannot be selected.
* **Avatar**: Display an avatar alongside the option. Set an **Icon Name**, **Image Source**, **Variant** (Circle or Square), **Initials**, and a presence indicator (**Type** and **Position**).
* **Value**: The field that provides a unique value for each option (defaults to `Record.Id`). This is the value stored when the option is selected.

### Content

#### Label

Enter a text label for the combobox, displayed above the input. The label supports expressions, so you can build it from record or variable data.

#### Value

Sets the default selected option. For the **Combobox Multiselect** variant, separate multiple values with a semicolon, or use **Value Collection** instead.

#### Value Collection

Provides the default selected options as a collection. *Requires: **Is Multi Select** = on.*

#### Field Level Help

Help text describing the purpose and function of the combobox, shown next to the label.

#### Variant

Changes the appearance of the combobox. Choose from:

* **Standard** (default) — label above the input.
* **Label Hidden** — hides the label for a clean, compact look.
* **Label Inline** — places the label beside the input.
* **Label Stacked** — stacks the label above the input.

#### Placeholder

Text displayed before an option is selected, prompting the user to make a selection.

#### Dropdown Alignment

Specifies where the dropdown list is anchored to the input field. Options: **Auto** (default), **Left**, **Center**, **Right**, **Bottom Left**, **Bottom Center**, and **Bottom Right**.

#### Dropdown Length

Sets the maximum visible height of the dropdown before it scrolls. Options: **5 Items**, **7 Items** (default), and **10 Items**.

#### Is Multi Select

Turn this on to allow multiple selections — this is what distinguishes the **Combobox Multiselect** preset from the single-select **Combobox**. Enabling it unlocks the **Maximum Selected Items**, **Minimum Selected Items**, range validation messages, **Value Collection**, and **Keep Open on Select** settings.

#### Maximum / Minimum Selected Items

Set the maximum and minimum number of options a user can select. *Requires: **Is Multi Select** = on.*

#### Message When Range Overflow / Underflow

Custom error messages shown when the number of selections exceeds the maximum (overflow) or falls below the minimum (underflow). *Requires: **Is Multi Select** = on.*

#### Keep Open on Select

When on, the dropdown menu stays open after an option is selected, making it easier to pick several options in a row. *Requires: **Is Multi Select** = on.*

#### Show Search

When on, the combobox options become searchable through a search input in the dropdown.

#### Hide Options Until Search

When on, the options stay hidden until the user types a search term. *Requires: **Show Search** = on.*

#### Required

When on, at least one option must be selected.

#### Disabled

When on, the combobox is disabled and users cannot interact with it.

#### Hide Clear Icon

When on, the input's clear icon is hidden so a selected option cannot be cleared from the input.

#### Hide Selected Options

When on, the selected-option pills are hidden. This is mainly relevant for the **Combobox Multiselect** variant.

### Actions

Add custom action items inside the dropdown — for example "Create new" or "Manage options" — and trigger behavior from the **On Action Click** interaction. Configure each action with:

* **Label**: The text shown for the action.
* **Name**: A unique identifier for the action (can be auto-filled from the label).
* **Icon Name**: An optional SLDS icon shown beside the label.
* **Position**: Whether the action appears at the **Top** (default) or **Bottom** of the dropdown.
* **Display on Search**: When on, the action appears only while searching.
* **Display When No Results**: When on, the action appears only when a search returns no results, and includes the search term (for example, *Create "{search}"*). *Requires: **Display on Search** = on.*
* **Fixed**: When on, the action stays visible regardless of scroll position in the dropdown.
* **Disabled**: When on, the action is disabled and cannot be clicked.

### 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 Combobox. Configure them from the **Interactions** tab of the Edit Combobox panel.

### Change

Fires whenever the user changes their selection. In the **Combobox Multiselect** variant, this includes adding or removing any option. Use it to navigate to a record, open a Screen Flow, store the selection in a variable, or refresh a dependent data source.

### Action Click

Fires when a user clicks one of the custom actions configured in the **Actions** section. Use the **targetName** output to identify which action was clicked and branch your flow logic accordingly.

## Styling

The Avonni Combobox component offers extensive styling options to help you integrate it into your Salesforce experience. Configure them from the **Style** tab of the Edit Combobox panel.

{% tabs %}
{% tab title="Margin" %}
Controls the outer spacing around the combobox.

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

{% tab title="Padding" %}
Controls the inner spacing within the combobox.

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

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

* **Width / Height:** Set fixed dimensions.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
* **Overflow / Overflow X / Overflow Y:** Control how overflowing content is handled.
  {% endtab %}

{% tab title="Label" %}
Styles the combobox label text.

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

{% tab title="Border" %}
Customizes the input field border.

* **Color:** Set the input border color.
* **Size:** Control the input border width.
* **Style:** Choose the input border line style.
* **Radius:** Round the input corners.
  {% endtab %}

{% tab title="Options" %}
Styles the background of each dropdown option.

* **Background Color:** Set the option background color, including its hover and disabled states.
  {% endtab %}

{% tab title="Options Label" %}
Styles the primary label text of each option.

* **Color:** Set the option label color, including hover and disabled states.
* **Font Size / Font Style / Font Weight:** Adjust the option label typography.
  {% endtab %}

{% tab title="Options Secondary Text" %}
Styles the subtext shown below each option label.

* **Color:** Set the secondary text color, including hover and disabled states.
* **Font Size / Font Style / Font Weight:** Adjust the secondary text typography.
  {% endtab %}

{% tab title="Options Avatar" %}
Styles the avatar displayed alongside each option.

* **Border Color / Size / Style / Radius:** Customize the avatar border.
* **Icon Background / Foreground Color:** Set the fallback icon colors, including disabled states.
* **Image Object Fit:** Control how avatar images fit their container.
* **Initials Color / Font Style / Font Weight:** Style the initials, including the hover color.
  {% endtab %}

{% tab title="Options Avatar Presence" %}
Styles the presence indicator on each option avatar.

* **Border Color / Radius:** Customize the presence indicator border.
* **Status Background Colors:** Set the background color for each presence status — Online, Busy, Focus, Offline, Blocked, and Away.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Combobox exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Item Selection

When a user picks an option, these variables update with the selected item's data.

| Output variable            | Type                           | What it returns                                                                                                                             |
| -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Selected Item**          | Object                         | The selected option's data — its label, value, secondary text, disabled state, and avatar.                                                  |
| **Selected Items**         | Object                         | All selected options as a collection, each with the same properties as a static data source item. Available when **Is Multi Select** is on. |
| **Selected Item sObject**  | Record (SObject)               | The full Salesforce record associated with the selected option. Requires a **Query** or **Variable** data source.                           |
| **Selected Items sObject** | Record Collection (SObject\[]) | The Salesforce records for all selected options. Requires a **Query** or **Variable** data source.                                          |
| **Value Comma Separated**  | Text (String)                  | The values of all selected options joined by a comma. Useful for passing multiple selections to a formula or filter.                        |

> **Example:** When a user selects a Contact from the combobox, use **Selected Item sObject** to display the Contact's details in a record-detail component on the same page.

### Actions

When a user clicks one of the custom dropdown actions, this variable identifies which one was clicked.

| Output variable         | Type          | What it returns                                          |
| ----------------------- | ------------- | -------------------------------------------------------- |
| **Clicked Action Name** | Text (String) | The name of the action the user clicked in the dropdown. |

> **Example:** Use **Clicked Action Name** in an interaction condition to branch logic between a "Create New" action and a "Manage Options" action in the same dropdown.

### Others

| Output variable     | Type          | What it returns                                                               |
| ------------------- | ------------- | ----------------------------------------------------------------------------- |
| **Number of Items** | Number        | The total number of options currently loaded in the combobox.                 |
| **Search Term**     | Text (String) | The text the user has typed into the search input. Updates as the user types. |


---

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