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.

Anchor to Migrate a contained taskMigrate a contained task

Migrating a sheet dialog

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>

</>

);

}

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>

<Button onClick={() => setOpen(false)}>Cancel</Button>

</div>

</div>

</Sheet>

</>

);

}

Polaris web components

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

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>
    </>
  );
}

Preview

Anchor to Replace Sheet responsibilitiesReplace 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.

Anchor to Test the migrationTest 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.

Anchor to Remove Polaris ReactRemove 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.

Anchor to Related guidanceRelated guidance

Was this page helpful?