---
title: Migrate to the Polaris sheet component
description: >-
  Learn how to migrate the Sheet component to Polaris web components in checkout
  and customer account UI extensions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/sheet'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/sheet.md
---

# Migrate to the Polaris sheet component

The Polaris sheet component displays supplementary content in an overlay panel. It replaces the previous [`Sheet`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/overlays/sheet) component and is available as [`<s-sheet>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/sheet) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris sheet component.

### primary​Action and secondary​Action

The previous `Sheet` `primaryAction` and `secondaryAction` props have been replaced with the [`primary-action`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/sheet#slots-propertydetail-primaryaction) and [`secondary-actions`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/sheet#slots-propertydetail-secondaryactions) slots.

| Previous prop | New pattern | Migration notes |
| - | - | - |
| `primaryAction` | `slot="primary-action"` | Place button children with `slot="primary-action"`. |
| `secondaryAction` | `slot="secondary-actions"` | Note the plural: `secondary-actions`. |

## Migrating action props to slots

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-button command="--show" commandFor="shipping-info">
        Edit shipping
      </s-button>
      <s-sheet id="shipping-info" heading="Shipping Information">
        <s-text-field label="Address"></s-text-field>
        <s-text-field label="City"></s-text-field>
        <s-button slot="primary-action">Save</s-button>
        <s-button slot="secondary-actions" variant="secondary">
          Cancel
        </s-button>
      </s-sheet>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Button,
  Sheet,
  TextField,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Sheet
      id="shipping-info"
      heading="Shipping Information"
      primaryAction={<Button>Save</Button>}
      secondaryAction={<Button>Cancel</Button>}
    >
      <TextField label="Address" />
      <TextField label="City" />
    </Sheet>
  );
}
```

***

## New properties

The Polaris sheet component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`onAfterShow`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/sheet#events-propertydetail-aftershow) | `function` | Fires after the sheet has fully opened and animations have completed. |
| [`onAfterHide`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/sheet#events-propertydetail-afterhide) | `function` | Fires after the sheet has fully closed and animations have completed. |

***

## New methods

The Polaris sheet component introduces a [`hideOverlay()`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/sheet#methods-propertydetail-hideoverlay) method for programmatically closing the sheet. This replaces the previous pattern of using `useApi()` and `ui.overlay.close()` to close overlays.

## Using hideOverlay to close the sheet

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useRef} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const sheetRef = useRef(null);

  function handleSave() {
    // Save data, then close the sheet
    sheetRef.current?.hideOverlay();
  }

  return (
    <>
      <s-button command="--show" commandFor="edit-sheet">
        Edit
      </s-button>
      <s-sheet id="edit-sheet" heading="Edit details" ref={sheetRef}>
        <s-text-field label="Name"></s-text-field>
        <s-button slot="primary-action" onClick={handleSave}>
          Save
        </s-button>
      </s-sheet>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Button,
  Sheet,
  TextField,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {ui} = useApi();

  function handleSave() {
    // Save data, then close the sheet
    ui.overlay.close('edit-sheet');
  }

  return (
    <Sheet
      id="edit-sheet"
      heading="Edit details"
      primaryAction={<Button onPress={handleSave}>Save</Button>}
    >
      <TextField label="Name" />
    </Sheet>
  );
}
```

***