---
title: Button group
description: >-
  The button group component displays multiple buttons in a contextual layout
  based on screen width or parent component. When there is more than one
  secondary action, they get collapsed.
api_version: 2026-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/button-group
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/button-group.md
---

# Button group

The button group component displays multiple [button](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/button) elements in a contextual layout based on screen width or parent component. When there is more than one secondary action, they get collapsed.

When used within a [section](https://shopify.dev/docs/api/customer-account-ui-extensions/web-components/layout-and-structure/section) component, the buttons fill the width of the section.

Button group accepts a single button in the `primary-action` slot — additional primary buttons are ignored. Secondary actions automatically collapse into an overflow menu when space is limited; the collapse threshold isn't configurable.

### Support Targets (24)

### Supported targets

* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Order management**: Group related order actions like "Reorder," "Edit order," and "Cancel order" in a structured layout.
* **Primary and secondary actions**: Combine a primary action with supporting secondary actions that collapse on smaller screens.
* **Account settings**: Group account-related actions like "Save changes" and "Reset" with clear visual hierarchy.

***

## Properties

Configure the following properties on the button group component.

* **accessibilityLabel**

  **string**

  A label that describes the purpose of the button group for users of assistive technologies such as screen readers. Use this to provide context about the grouped actions, such as "Order actions" or "Profile settings."

* **id**

  **string**

  A unique identifier for the element. Use this to target the element with CSS, JavaScript, or accessibility attributes. The `id` must be unique within the document.

### Slots

The button group component supports slots for additional content placement within the component. Learn more about [using slots](https://shopify.dev/docs/api/polaris/using-polaris-web-components#slots).

* **primary-action**

  **HTMLElement**

  The primary action for the group. Accepts a single [button](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/button) element. Use this for the most important action in the group, such as "Save" or "Submit."

* **secondary-actions**

  **HTMLElement**

  The secondary actions for the group. Accepts multiple [button](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/button) elements. Use this for supplementary actions like "Cancel", "Delete", or other alternatives.

***

## Examples

### Add primary and secondary actions

Display a primary action alongside secondary options. This example shows an `s-button-group` with a primary button and a secondary dropdown menu for order management.

## Add primary and secondary actions

![A button group with a primary Reorder button and a secondary Manage dropdown menu.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/customer-account-ui-extensions/2025-10/button-group-default-DN6juDlh.png)

## html

```html
<s-button-group>
  <s-button slot="primary-action" variant="primary">
    Reorder
  </s-button>
  <s-button slot="secondary-actions" variant="secondary" commandFor="manage-menu" command="--show">
    Manage
  </s-button>
  <s-menu id="manage-menu">
    <s-choice value="track">Track order</s-choice>
    <s-choice value="return">Return items</s-choice>
    <s-choice value="cancel">Cancel order</s-choice>
  </s-menu>
</s-button-group>
```

### Use a single primary action

Display a standalone primary action within a button group layout. This example shows an `s-button-group` with a single primary button for updating account preferences.

## html

```html
<s-button-group>
  <s-button slot="primary-action" variant="primary">
    Update preferences
  </s-button>
</s-button-group>
```

### Collapse multiple secondary actions

Automatically collapse extra secondary actions into an overflow menu on smaller screens. This example shows an `s-button-group` with one primary and three secondary buttons.

## html

```html
<s-button-group>
  <s-button slot="primary-action" variant="primary">
    Continue
  </s-button>
  <s-button slot="secondary-actions" variant="secondary">
    Edit address
  </s-button>
  <s-button slot="secondary-actions" variant="secondary">
    Add note
  </s-button>
  <s-button slot="secondary-actions" variant="secondary">
    Apply discount
  </s-button>
</s-button-group>
```

***

## Best practices

* **Use a single primary action**: Reserve the `primary-action` slot for one button only. Keep all other actions in `secondary-actions` to reinforce hierarchy.
* **Write short, scannable labels**: Use verbs and nouns in sentence case, such as "Edit address." Keep styling consistent across actions.
* **Limit secondary actions**: Reduce clutter by keeping the number of secondary actions small. Extra actions collapse automatically on smaller screens.
* **Group related actions**: Cluster actions by purpose and place the most important or common action first to set a clear default.

***