SButtonGroup <s-button-group>

Lays out a set of related buttons together, such as a primary action and its secondary actions. SButtonGroup is the typed Vue 3 wrapper for Shopify's Polaris <s-button-group> web component.

import { SButtonGroup } from 'polaris-vue-elements'

Best practices

• Keep related actions together. Group calls to action that belong to the same task so merchants can see their options and how they relate.
• Keep a visual hierarchy. Use variant="primary" on the button for the main action and variant="secondary" or variant="tertiary" on the supporting ones to steer attention.
• Don't add too many buttons. A long row of choices overwhelms merchants and makes it harder to decide.
• Use a segmented group for toggles. For closely related options, such as switching views or filters, set gap="none" to join the buttons into one segmented control.
• Set destructive actions apart. Place them deliberately and give them tone="critical" so they're harder to trigger by accident.

<SButtonGroup gap="none">
  <SButton>List</SButton>
  <SButton>Grid</SButton>
</SButtonGroup>

See Shopify's best practices for <s-button-group> for the full guidance.

Example

SaveCancelDiscard

ListGrid

<script setup>
import { SButton, SButtonGroup, SPressButton } from 'polaris-vue-elements'
</script>

<template>
  <!-- primary-action accepts a single variant="primary" button; secondary-actions
       accepts Button (variant "secondary" or "auto") and PressButton (variant
       "secondary", its default) elements. The default slot is NOT rendered by the
       underlying <s-button-group> — content without one of these slots silently
       disappears. -->
  <SButtonGroup>
    <template #primary-action>
      <SButton variant="primary">Save</SButton>
    </template>
    <template #secondary-actions>
      <SButton variant="secondary">Cancel</SButton>
      <SButton variant="secondary">Discard</SButton>
    </template>
  </SButtonGroup>

  <!-- Segmented toggle: gap="none" joins the buttons. primary-action is not
       supported with gap="none", so every button goes in secondary-actions. -->
  <SButtonGroup gap="none" accessibilityLabel="View style">
    <template #secondary-actions>
      <SPressButton>List</SPressButton>
      <SPressButton pressed>Grid</SPressButton>
    </template>
  </SButtonGroup>
</template>

Props

Prop	Type	Description
accessibilityLabel	string	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.
gap	"base" | "none"	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.

Slots

Slot	Description
default	The buttons displayed within the button group component, which are arranged together as a cohesive set of related actions.
primary-action	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".
secondary-actions	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.