---
title: Migrate Popover to the Polaris popover component
description: >-
  Learn how to migrate the Popover 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/popover
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/popover.md
---

# Migrate Popover to the Polaris popover component

The Polaris popover component displays transient content anchored to a trigger. It replaces the previous [`Popover`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/overlays/popover) component and is available as [`<s-popover>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris popover component.

### on​Open

The previous `Popover` `onOpen` prop is now called [`onShow`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#events-propertydetail-show). The handler now receives an `Event` instead of being called with no arguments.

### on​Close

The previous `Popover` `onClose` prop is now called [`onHide`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#events-propertydetail-hide). The handler now receives an `Event` instead of being called with no arguments.

### Sizes

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

| Property | Previous values | New values | Migration notes |
| - | - | - | - |
| [`maxInlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#properties-propertydetail-maxinlinesize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'none'` | `fill` is removed. Use `100%` instead. |
| [`minInlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#properties-propertydetail-mininlinesize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` | `fill` is removed. Use `100%` instead. |

***

## Updated patterns

### Activation

The previous pattern of nesting `Popover` inside a trigger's `overlay` prop has been replaced with [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button#properties-propertydetail-command) and [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button#properties-propertydetail-commandfor) on the trigger, targeting a sibling [`<s-popover>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover) by ID.

| Previous pattern | New pattern |
| - | - |
| `overlay={<Popover>…</Popover>}` on a trigger (Button, Link, or Pressable) | `command="--toggle"` + `commandFor="popover-id"` on the trigger pointing to a sibling `<s-popover id="popover-id">…</s-popover>` |

**Tip:**

The `command` prop defaults to `--auto`, which resolves to `--toggle` for popovers. You can omit `command` when targeting a popover and only set `commandFor`.

## Migrating Popover to s-popover

##### Latest (Preact)

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

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

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

***

## New properties

The Polaris popover component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`blockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#properties-propertydetail-blocksize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'auto'` | Adjusts the block size of the popover. |
| [`inlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#properties-propertydetail-inlinesize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'auto'` | Adjusts the inline size of the popover. |
| [`maxBlockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#properties-propertydetail-maxblocksize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'none'` | Adjusts the maximum block size of the popover. |
| [`minBlockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover#properties-propertydetail-minblocksize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` | Adjusts the minimum block size of the popover. |

***

## Removed properties

### alignment 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.

### padding

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>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box) with extra padding.

***