> 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-group.md).

# Button Group

The Button Group component combines multiple buttons into a single cohesive unit, organizing related actions in a compact, user-friendly layout. Use it whenever you want to present a set of related actions — such as toolbar commands or form actions — together.

## Overview

A Button Group lets you define any number of buttons, each with its own label, icon, variant, and visibility state. You can arrange the buttons in a compact group or spaced out in a row, and — when you have more actions than space allows — move the overflow buttons into a dropdown menu to keep the interface clean.

**Why use the Button Group component?**

* **Organize actions:** Group related actions together for a more intuitive user experience.
* **Improve visual appeal:** Present buttons in a consistent, organized manner.
* **Optimize space:** Use the overflow menu to manage many buttons without cluttering the interface.
* **Enhance consistency:** Maintain a uniform style and layout for buttons across your application.

## Configuration

To configure the Button Group, select it on the canvas. The **Edit Button Group** 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%2FMnBjP7WZmfsaxH4VnYFs%2Fbutton-group-builder-properties.png?alt=media" alt="" width="375"><figcaption><p>The Properties tab of the Edit Button Group panel, with the Buttons collection and the Button Menu section.</p></figcaption></figure>

### Properties

#### Display as Row

When enabled, the buttons are rendered as separated items spaced out in a row, instead of the default compact grouped layout where buttons sit flush against one another.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FWfpzdhJ0fbXZxILLXCnb%2Fbutton-group-display-as-row.png?alt=media" alt=""><figcaption><p>The same three buttons with Display as Row off and on.</p></figcaption></figure>

#### Stretch

When enabled, the group fills the width of its container and the buttons share the space between them. Leave it off to keep the group at its content width, which is what the header's horizontal alignment positions.

Buttons that show only an icon keep their own width, so the labelled buttons take the extra space rather than leaving a gap around a centred icon. Buttons never shrink below their label, so a group that runs out of room still moves its last buttons into the overflow menu.

#### Visible Buttons

Sets the maximum number of buttons to display. Any buttons beyond this count are moved into the overflow button menu (configured below). If left unset, all buttons are displayed.

#### Buttons

Add and order the buttons that make up the group. Each button exposes the following settings:

| Setting           | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| **Label**         | The text displayed on the button.                                                                             |
| **Icon Name**     | A Lightning Design System icon to display on the button.                                                      |
| **Icon Position** | Where the icon sits relative to the label — **Left** (default) or **Right**. Applies once a label is set.     |
| **Icon Source**   | A custom image URL to use as the button icon instead of a Lightning icon.                                     |
| **Variant**       | Changes the appearance of the button. Defaults to **Neutral**. See the variant list below.                    |
| **Disabled**      | Prevents the button from being clicked.                                                                       |
| **Hidden**        | Hides the button from the group.                                                                              |
| **Title**         | Tooltip text shown when hovering over the button.                                                             |
| **Name**          | A unique identifier for the button within the group. Required, and used to target the button in interactions. |

The **Variant** options are: Bare, Bare Inverse, Base, Border, Border Filled, Border Inverse, Brand, Brand Outline, Container, Destructive, Destructive Text, Inverse, Neutral, and Success.

### Button Menu

The Button Menu section configures the overflow dropdown that appears when **Visible Buttons** limits how many buttons are shown. Any buttons beyond the visible count are collected into this menu.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F7FLb6mhQhYKsZ9BiXDiI%2Fbutton-group-overflow.png?alt=media" alt=""><figcaption><p>Five buttons with Visible Buttons set to 3: the remaining two appear in the overflow menu.</p></figcaption></figure>

| Setting            | Description                                                                                                                                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label**          | The text displayed on the menu button that opens the dropdown.                                                                                                                                                              |
| **Icon Name**      | A Lightning Design System icon to display on the menu button.                                                                                                                                                               |
| **Variant**        | Changes the appearance of the menu button. Defaults to **Border Filled**.                                                                                                                                                   |
| **Menu Alignment** | Where the dropdown opens relative to the menu button — **Auto** (default), **Left**, **Center**, **Right**, **Bottom Left**, **Bottom Center**, or **Bottom Right**. Auto places the menu wherever it fits in the viewport. |

The menu button **Variant** options are: Bare, Bare Inverse, Border, Border Filled, Border Inverse, Brand, Brand Outline, Container, Destructive, Destructive Text, Inverse, Neutral, and Success.

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

* **Toolbar:** Create a toolbar with buttons for common actions like New, Edit, Delete, and Save.
* **Navigation:** Group navigation buttons together for easy access to different sections of your application.
* **Form Actions:** Combine Submit and Cancel buttons in a visually cohesive unit.
* **Workflow Actions:** Present a set of actions related to a specific workflow or process.

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Button Group. Configure them from the **Interactions** tab of the Edit Button Group panel.

### Click

Fires when a user clicks a button in the group.

The interaction carries a **Target Name** setting: pick a button there to run the interaction only for that button, matched against the button's **Name**. Leave it empty to run the interaction for every button in the group.

To branch on which button was clicked from elsewhere on the page, use the **Clicked Button Name** output variable described below rather than the Target Name setting.

## Styling

The Button Group offers extensive styling options to help you integrate it into your Salesforce environment. Configure them from the **Style** tab of the Edit Button Group panel.

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

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

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

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

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

* **Color / Size / Style / Radius:** Customize the group border.
  {% endtab %}

{% tab title="Horizontal Alignment" %}

* **Horizontal Alignment:** Align the button group within its container.
  {% endtab %}

{% tab title="Container" %}

* **Background Color:** Set the background color of the group container.
  {% endtab %}

{% tab title="Label" %}

* **Font Size / Font Style / Font Weight / Font Family:** Customize the typography of the button labels.
  {% endtab %}

{% tab title="Buttons Border" %}

* **Size / Style:** Adjust the border size and line style applied to the buttons.
  {% endtab %}

{% tab title="Variants" %}
Each button variant has its own color group (set per variant: **Bare**, **Bare Inverse**, **Base**, **Border**, **Border Filled**, **Border Inverse**, **Brand**, **Brand Outline**, **Container**, **Destructive**, **Destructive Text**, **Inverse**, **Neutral**, **Success**).

* **Background Color, Text Color, Border Color:** Customize each across the default, active, and hover states of buttons using that variant.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Button Group exposes this output variable you can reference elsewhere on the page after the user interacts with it.

### Button Click

When a user clicks a button in the group, this variable updates with the clicked button's identity.

| Output variable         | Type          | What it returns                              |
| ----------------------- | ------------- | -------------------------------------------- |
| **Clicked Button Name** | Text (String) | The **Name** of the button the user clicked. |

> **Example:** When a user clicks a button named `delete`, use **Clicked Button Name** to conditionally show a confirmation dialog component on the same page.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/button-group.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.