Migrate ButtonGroup from Polaris React

Use s-button-group for a small set of related local actions. Move actions that define the page to s-page's primary-action and secondary-actions slots.

Anchor to Migrate a local action groupMigrate a local action group

Migrating form actions

<s-button-group>

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

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

</s-button-group>

import {Button, ButtonGroup} from '@shopify/polaris';

<Button onClick={cancel}>Cancel</Button>

</ButtonGroup>

Polaris web components

<s-button-group>
  <s-button slot="primary-action">Save</s-button>
  <s-button slot="secondary-actions">Cancel</s-button>
</s-button-group>

Polaris React

import {Button, ButtonGroup} from '@shopify/polaris';

<ButtonGroup>
  <Button onClick={cancel}>Cancel</Button>
  <Button variant="primary" onClick={save}>Save</Button>
</ButtonGroup>

Preview

Place supporting buttons in slot="secondary-actions" and the main action in slot="primary-action". The group owns ordering and responsive presentation.

Anchor to Replace group behaviorReplace group behavior

Polaris React	Polaris web components	Migration notes
Child `Button` elements	Child `s-button` elements	Migrate each button's behavior independently.
Primary action	`slot="primary-action"`	Use at most one primary action in the group.
Other actions	`slot="secondary-actions"`	Order them by task importance.
`segmented`	Grouped buttons only when the actions form one control	Use a choice field for persistent selection.
`fullWidth`	Containing grid or stack	Don't stretch low-priority actions solely to match old styling.
`connectedTop`	Remove	Place the group in the destination section or page layout.
`noWrap`	Destination responsive behavior	Shorten labels or move infrequent actions to a menu.

Don't move every overflowed action into a menu automatically. Keep frequent actions visible and put contextual, lower-frequency actions in an s-menu opened by a sibling button.

Anchor to Test the migrationTest the migration

Verify action order and hierarchy at narrow and wide widths.
Exercise loading and disabled states without shifting the primary action unexpectedly.
Confirm form submit and cancel behavior, including keyboard order.
Test overflow-menu focus return where used.

Anchor to Remove Polaris ReactRemove Polaris React

Remove ButtonGroup, layout wrappers used only to space it, and old overflow logic after the action hierarchy is migrated. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Related guidanceRelated guidance

Was this page helpful?