---
title: Migrate ButtonGroup from Polaris React
description: >-
  Replace Polaris React ButtonGroup with s-button-group or page action slots
  while preserving action hierarchy and overflow behavior.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/button-group
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/button-group.md
api_name: app-home
---

# Migrate Button​Group from Polaris React

Use [`s-button-group`](https://shopify.dev/docs/api/app-home/web-components/actions/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.

***

## Migrate a local action group

## Migrating form actions

##### Polaris web components

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

##### Polaris React

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

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

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

***

## Replace 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.

***

## Test 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.

***

## Remove 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.

***

## Related guidance

* [Button group component](https://shopify.dev/docs/api/app-home/web-components/actions/button-group)
* [Migrate PageActions from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/page-actions)
* [Migrate ActionList from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/action-list)

***