Migrate Popover to the Polaris popover component

The Polaris popover component displays transient content anchored to a trigger. It replaces the previous Popover component and is available as <s-popover> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris popover component.

Anchor to onOpenonOpen

The previous Popover onOpen prop is now called onShow. The handler now receives an Event instead of being called with no arguments.

Anchor to onCloseonClose

The previous Popover onClose prop is now called onHide. The handler now receives an Event instead of being called with no arguments.

Anchor to SizesSizes

The size properties accept updated values in the Polaris popover component. Previous unitless number values map to pixels. For example, 300 is now '300px'.

Anchor to Updated patternsUpdated patterns

Anchor to ActivationActivation

The previous pattern of nesting Popover inside a trigger's overlay prop has been replaced with command and commandFor on the trigger, targeting a sibling <s-popover> by ID.

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

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

function Extension() {
  return (
    <>
      <s-button command="--toggle" commandFor="details">
        Show details
      </s-button>
      <s-popover id="details">
        <s-text>Free shipping on orders over $50.</s-text>
      </s-popover>
    </>
  );
}

import {
  reactExtension,
  Button,
  Popover,
  Text,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  return (
    <Button
      overlay={
        <Popover>
          <Text>Free shipping on orders over $50.</Text>
        </Popover>
      }
    >
      Show details
    </Button>
  );
}

Anchor to New propertiesNew properties

The Polaris popover component introduces the following new properties:

Anchor to Removed propertiesRemoved properties

Anchor to alignment and positionalignment and position

The previous Popover alignment and position props have been removed. The Polaris popover positions itself relative to the trigger automatically and repositions to avoid overflowing the viewport — which was the primary use case for the previous alignment and position props.

Anchor to paddingpadding

The previous Popover padding prop has been removed. The Polaris popover applies its own built-in padding that can't be removed or overridden. If you need additional space around the content, wrap it in an <s-box> with extra padding.