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

# Button Menu

The Avonni Button Menu component displays a button that opens a dropdown menu. Use it whenever you need to surface a compact set of actions or choices — the menu can be triggered by click, hover, or focus, and supports label and/or icon triggers, a search input, a selection checkmark, and a draft indicator.

## Overview

To start with the Avonni Button Menu component, you'll first need to connect it to your data and configure how it is displayed. The sections below follow the configuration panel from top to bottom, so you can read along as you build.

## Configuration

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

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F7g1658n15PZWFn4wR5Mk%2Fbutton-menu-builder-properties.png?alt=media" alt="" width="375"><figcaption><p>The Properties tab of the Edit Button Menu panel, from the data source down through the Content settings.</p></figcaption></figure>

### Data Source

Before you build your menu, you must tell the Avonni Button Menu component where to get the items 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="/dynamic-components/component-builder/data-sources/picklist.md">Picklist</a></td></tr></tbody></table>

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F6RW364nGjmDpyqtNgjNm%2Fbutton-menu-builder-data.png?alt=media" alt="" width="375"><figcaption><p>The data source switch and, with Manual selected, the Menu Items collection.</p></figcaption></figure>

#### Menu Items

With the **Manual** data source, the **Menu Items** collection holds the items themselves. Add, reorder and remove them there. Each item exposes the following settings:

| Setting                    | Description                                                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label**                  | The text displayed for the menu item.                                                                                                        |
| **Value**                  | A unique value for the item, used for selection and for the checkmark. Required: an item saved without a value is not displayed in the menu. |
| **Icon Name**              | A Lightning Design System icon displayed before the label.                                                                                   |
| **Is Draft**               | Shows a draft indicator, a blue asterisk, on the item.                                                                                       |
| **Draft Alternative Text** | Describes the reason for showing the draft indicator.                                                                                        |
| **URL**                    | The address the item links to.                                                                                                               |
| **Target**                 | Where the URL opens: **Self** (default), **Blank**, **Parent**, or **Top**. Requires **URL** to be set.                                      |
| **Disabled**               | Prevents the item from being selected.                                                                                                       |
| **Hidden**                 | Hides the item from the menu.                                                                                                                |

### Data Mapping

When using a dynamic data source for your Button Menu, configure the **Data Mappings** section to tell the component how to map your data fields to menu item properties such as label, value, and icon.

### Content

#### Variant

The **Variant** setting changes the visual appearance of the button trigger. The default value when no label is set is **Border**; the default when a label is present is **Neutral**.

Available variants: Bare, Bare Inverse, Base, Border, Border Filled, Border Inverse, Brand, Brand Outline, Container, Destructive, Destructive Text, Inverse, Neutral, and Success.

#### Label

Optional text displayed on the button trigger alongside the icon.

#### Icon Name

The Lightning Design System name of the icon shown on the button (for example, `utility:settings`). If an icon other than `utility:down` or `utility:chevrondown` is used, a down-arrow icon is appended to the right of it (unless **Hide Down Arrow** is enabled).

#### Icon Size

Controls the size of the trigger icon. Options: **Xxs**, **Xs**, **Small**, **Medium** (default), **Large**.

#### Icon Source

A URL or Content Document ID for a custom image to use as the trigger icon instead of a Lightning Design System icon.

#### Menu Alignment

Determines where the dropdown appears relative to the button. Options: **Auto**, **Left** (default), **Center**, **Right**, **Bottom Left**, **Bottom Center**, **Bottom Right**.

#### Menu Length

Sets the maximum visible height of the dropdown. Options: **None** (default, no restriction), **5 Items**, **7 Items**, **10 Items**.

#### Menu Trigger

Specifies the user action that opens the menu. Options: **Click** (default), **Hover**, **Focus**.

#### Tooltip

Text displayed when the user mouses over or focuses on the button.

#### Hide Down Arrow

When enabled, hides the additional down-arrow that normally appears to the right of a custom icon.

#### Hide Checkmark

When enabled, hides the checkmark that indicates the currently selected menu item. The checkmark is otherwise shown next to the item whose value matches the **Value** setting.

#### Nubbin

When enabled, adds a nubbin (a small pointer stub) to the menu. The nubbin position follows the **Menu Alignment** setting.

#### Disabled

When enabled, the menu cannot be opened by users.

#### Alternative Text

Assistive text for the button menu, used by screen readers.

#### Is Draft

When enabled, the button trigger shows a draft indicator (a blue asterisk).

#### Draft Alternative Text

Describes the reason for showing the draft indicator. Required when **Is Draft** is enabled.

#### Title

Text displayed as a tooltip when the user hovers over the button menu trigger.

#### Value

The currently selected value. When set, a checkmark appears next to the menu item whose value matches this setting.

#### Show Search

When enabled, a search input appears at the top of the dropdown, allowing users to filter the menu items.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FphxkSMt3FuCmL1ir3WDB%2Fbutton-menu-dropdown.png?alt=media" alt=""><figcaption><p>The menu open with search enabled, and the checkmark on the item matching Value.</p></figcaption></figure>

#### Search Input Placeholder

Placeholder text shown in the search input when it is empty. Requires **Show Search** to be enabled.

### Actions

Actions are additional buttons displayed at the footer of the Button Menu dropdown. Each action has a **Label**, a **Name** (a unique identifier used in interactions), and an optional **Icon Name**.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FwrMAgdfBYE8pRy4HTEpb%2Fbutton-menu-actions.png?alt=media" alt=""><figcaption><p>Two actions at the footer of the dropdown, below the menu items.</p></figcaption></figure>

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

### Select

Fires when a user selects a menu item. Use the **Selected Item** output variable described below to read which item was chosen and drive downstream logic such as navigation, record updates, or opening a flow screen.

With the **Manual** data source, the interaction also carries a **Target Name** setting: pick a menu item there to run the interaction only for that item, matched against the item's **Value**. The setting is not offered for the **Variable**, **Query**, and **Picklist** data sources, where one Select interaction runs for every item.

### Action Click

Fires when a user clicks one of the footer actions.

The interaction carries a **Target Name** setting: pick an action there to run the interaction only for that action. To branch on which action was clicked from elsewhere on the page, use the **Clicked Action - Name** output variable described below.

## Styling

Configure the Button Menu's appearance from the **Style** tab of the Edit Button Menu panel. The color sections below adapt to the **Variant** chosen in the Properties tab.

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

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

{% tab title="Padding" %}
Controls the *inner* spacing inside the button.

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

{% tab title="Horizontal Alignment" %}
Sets the horizontal alignment of the button within its container.

* **Horizontal Alignment:** Choose how the button is justified.
  {% endtab %}

{% tab title="Text/Icon" %}
Customizes the trigger's label and icon (color set per variant).

* **Font Size / Font Style / Font Weight / Font Family:** Adjust the label typography.
* **Color / Color Active / Color Hover:** Set the text and icon color in each state.
  {% endtab %}

{% tab title="Border" %}
Customizes the button border (color set per variant).

* **Size:** Adjust the border thickness.
* **Style:** Set the border style (solid, dashed, dotted, etc.).
* **Radius:** Control the roundness of the corners.
* **Color / Color Active / Color Hover:** Set the border color in each state.
  {% endtab %}

{% tab title="Background" %}
Sets the button background (color set per variant).

* **Color / Color Active / Color Hover:** Set the background color in each state.
  {% endtab %}

{% tab title="Spacing" %}
Adjusts the internal block and inline spacing of the button (set per variant).

* **Block Start / Block End:** Set the vertical spacing.
* **Inline Start / Inline End:** Set the horizontal spacing.
  {% endtab %}

{% tab title="Image" %}
Applies when a custom image is used via **Icon Source**.

* **Border Color / Border Size / Border Style / Border Radius:** Customize the image border.
* **Image Object Fit:** Control how the image fills its area.
  {% endtab %}
  {% endtabs %}

## Output Variables

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

### Item Selection

When a user selects a menu item, these variables update with the chosen item's data. They are also populated when the page loads if **Value** is already set, so a menu that starts on a preselected item exposes that item without waiting for a click.

| Output variable           | Type             | What it returns                                                                                                 |
| ------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **Selected Item**         | Object           | The selected menu item's data — its label, value, URL, icon name, and target.                                   |
| **Selected Item sObject** | Record (SObject) | The full Salesforce record associated with the selected item. Requires a **Query** or **Variable** data source. |

> **Example:** When a user picks a status from the Button Menu, use **Selected Item** to read its value and update a record field, or use **Selected Item sObject** to pass the full record to a detail component on the same page.

### Action Click

When a user clicks one of the footer actions, this variable identifies which action was triggered.

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

> **Example:** Add a "Delete" footer action and branch page logic on **Clicked Action - Name** to show a confirmation modal only when that specific action is triggered.

### Others

| Output variable     | Type    | What it returns                                         |
| ------------------- | ------- | ------------------------------------------------------- |
| **Clicked**         | Boolean | `true` while a menu item selection event is firing.     |
| **Number of Items** | Number  | The total number of items currently loaded in the menu. |


---

# 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/button-menu.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.