Button group

The button group component displays multiple related buttons in a structured layout. Use button group to organize action buttons together, creating clear visual hierarchies and helping users understand available options.

Button groups support various layouts including segmented appearances for tightly related options like view switching or filter controls. For individual actions, use button.

Anchor to PropertiesProperties

Configure the following properties on the button group component.

Anchor to gap gap "base" | "none" Default: 'base' required: The spacing between buttons in the group.

base: Standard spacing that provides clear visual separation between buttons.

none: No spacing, creating a connected button group.
Anchor to accessibilityLabel accessibilityLabel string required: A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.

Anchor to SlotsSlots

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

Anchor to children children HTMLElement: The buttons displayed within the button group component, which are arranged together as a cohesive set of related actions.
Anchor to primary-action primary-action HTMLElement: The main action for this group, displayed with high visual emphasis. Accepts a single button with variant="primary".

Use this for the primary action you want users to take. This can't be used when gap="none".
Anchor to secondary-actions secondary-actions HTMLElement: Supporting actions displayed with less emphasis than the primary action. Accepts one or more button components with variant="secondary" or variant="auto".

Use these for alternative or less critical actions.

Anchor to ExamplesExamples

Anchor to Group a primary and secondary actionGroup a primary and secondary action

Group related buttons together with a primary action and secondary options. This example shows a button group with a save button and a cancel button.

Preview

html

<s-button-group>

<s-button slot="primary-action">Save</s-button>

<s-button slot="secondary-actions">Cancel</s-button>

</s-button-group>

Anchor to Add bulk action buttonsAdd bulk action buttons

Present multiple secondary actions for operating on selected items. This example shows archive, export, and delete buttons grouped together for bulk operations.

Preview

html

<s-button-group>

<s-button slot="secondary-actions">Archive</s-button>

<s-button slot="secondary-actions">Export</s-button>

<s-button slot="secondary-actions" tone="critical">Delete</s-button>

</s-button-group>

Anchor to Add icons to grouped buttonsAdd icons to grouped buttons

Add icons to grouped buttons to help merchants identify each action. This example shows duplicate, archive, and delete buttons with icons.

Preview

html

<s-button-group>

<s-button slot="secondary-actions" icon="duplicate">Duplicate</s-button>

<s-button slot="secondary-actions" icon="archive">Archive</s-button>

<s-button slot="secondary-actions" icon="delete" tone="critical">

Delete

</s-button>

</s-button-group>

Anchor to Create a segmented button groupCreate a segmented button group

Remove the gap between buttons to create a segmented control for toggling between views or options. This example shows day, week, and month buttons joined together with no spacing.

Preview

html

<s-button-group gap="none">

<s-button slot="secondary-actions">Day</s-button>

<s-button slot="secondary-actions">Week</s-button>

<s-button slot="secondary-actions">Month</s-button>

</s-button-group>

Anchor to Confirm a destructive actionConfirm a destructive action

Pair a cancel button with a critical action for destructive confirmation flows. This example shows a cancel and delete button grouped together for a confirmation dialog.

Preview

html

<s-button-group>

<s-button slot="secondary-actions">Cancel</s-button>

<s-button slot="secondary-actions" tone="critical">Delete product</s-button>

</s-button-group>

Anchor to Best practicesBest practices

Group related actions: Organize related calls to action together to create clear action hierarchies and help merchants understand available options.
Maintain visual hierarchy: Use primary variants for main actions and secondary or tertiary variants for supporting actions to guide merchant attention.
Limit action count: Avoid including too many buttons, which can overwhelm merchants and create decision paralysis.
Use segmented appearance for toggles: Apply the segmented appearance for tightly related options like view switching or filter controls.
Separate destructive actions: Position destructive actions appropriately and use critical tone to prevent accidental activation.

Was this page helpful?