Migrate to the Polaris sheet component

The Polaris sheet component displays supplementary content in an overlay panel. It replaces the previous Sheet component and is available as <s-sheet> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris sheet component.

Anchor to primaryAction and secondaryActionprimaryAction and secondaryAction

The previous Sheet primaryAction and secondaryAction props have been replaced with the primary-action and secondary-actions slots.

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

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

Anchor to New propertiesNew properties

The Polaris sheet component introduces the following new properties:

Anchor to New methodsNew methods

The Polaris sheet component introduces a hideOverlay() method for programmatically closing the sheet. This replaces the previous pattern of using useApi() and ui.overlay.close() to close overlays.

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

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