Choose a version:

Button group

The button group component displays multiple 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 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

Anchor to PropertiesProperties

Configure the following properties on the button group component.

Anchor to accessibilityLabel 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."
Anchor to id 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.

Anchor to SlotsSlots

The button group component supports slots for additional content placement within the component. Learn more about using slots.

Anchor to primary-action primary-action HTMLElement: The primary action for the group. Accepts a single button element. Use this for the most important action in the group, such as "Save" or "Submit."
Anchor to secondary-actions secondary-actions HTMLElement: The secondary actions for the group. Accepts multiple button elements. Use this for supplementary actions like "Cancel", "Delete", or other alternatives.

Anchor to ExamplesExamples

Anchor to Add primary and secondary actionsAdd 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.

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>

Anchor to Use a single primary actionUse 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

<s-button-group>

<s-button slot="primary-action" variant="primary">

Update preferences

</s-button>

</s-button-group>

Anchor to Collapse multiple secondary actionsCollapse 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

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

Anchor to Best practicesBest 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.

Was this page helpful?