---
title: Migrate Sheet from Polaris React
description: >-
  Replace Polaris React Sheet with s-modal for a contained dialog or
  s-app-window for a dedicated workflow.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/sheet
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/sheet.md
api_name: app-home
---

# Migrate Sheet from Polaris React

Polaris web components don't have a sheet presentation. Choose the destination by task scope:

| Existing Sheet task | Polaris web components | Migration type |
| - | - | - |
| Confirmation, short form, or contained dialog | `s-modal` | Change presentation |
| Dedicated, multi-section workflow | `s-app-window` with its own page | Change pattern |
| Contextual supporting controls | `s-popover` when content remains brief | Change presentation |

Don't preserve a side or bottom sheet solely to match the old responsive treatment.

***

## Migrate a contained task

## Migrating a sheet dialog

##### Polaris web components

```tsx
export function EditTagsDialog({save}: {save(): void}) {
  return (
    <>
      <s-button commandFor="edit-tags-modal">Edit tags</s-button>
      <s-modal id="edit-tags-modal" heading="Edit product tags">
        <s-text>Tag form</s-text>
        <s-button slot="primary-action" variant="primary" onClick={save}>
          Save
        </s-button>
        <s-button
          slot="secondary-actions"
          commandFor="edit-tags-modal"
          command="--hide"
        >
          Cancel
        </s-button>
      </s-modal>
    </>
  );
}
```

##### Polaris React

```tsx
import {useState} from 'react';
import {Button, Sheet} from '@shopify/polaris';

export function EditTagsSheet({save}) {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Edit tags</Button>
      <Sheet open={open} onClose={() => setOpen(false)} accessibilityLabel="Edit product tags">
        <div>
          <div>
            <Button onClick={() => setOpen(false)}>Cancel</Button>
            <Button variant="primary" onClick={save}>Save</Button>
          </div>
          <div>Tag form</div>
        </div>
      </Sheet>
    </>
  );
}
```

***

## Replace Sheet responsibilities

| Polaris React | Destination | Migration notes |
| - | - | - |
| `open` and `onClose` | Trigger `commandFor` plus modal or app-window behavior | Remove React state used only to host the overlay where possible. |
| `accessibilityLabel` | `heading` on `s-modal` or page heading in `s-app-window` | Use a visible task name. |
| `Sheet.Header` | Modal heading and action slots, or `s-page` actions | Keep one primary action and a clear cancel path. |
| `Sheet.Content` | Modal content or dedicated route content | Keep field values and validation with the task. |
| Mobile-only presentation | Destination responsive behavior | Test the embedded container rather than viewport assumptions. |

Use `s-modal` for work that can be understood and completed without navigating through multiple sections. Use `s-app-window` when the workflow needs page structure, substantial editing, or its own unsaved-change protection.

Preserve draft state when save fails. Close only after success or explicit cancel. Confirm discard when closing would lose meaningful changes, and return focus to the trigger.

***

## Test the migration

* Open and close with trigger, cancel, Escape, and successful completion.
* Verify focus moves into the task and returns to the trigger.
* Exercise validation, pending, failure, retry, and discard confirmation.
* Test narrow and wide embedded containers with long content.
* Confirm browser navigation and save-bar behavior for an app-window workflow.

***

## Remove Polaris React

Remove `Sheet` and its subcomponents, host containers, and overlay state after each workflow uses the chosen destination. Remove `@shopify/polaris` only after no other route in scope imports it.

***

## Related guidance

* [Migrate Modal from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/modal)
* [App window](https://shopify.dev/docs/api/app-home/app-bridge-web-components/app-window)
* [Migrate Popover from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/popover)

***