---
title: Popover
description: >-
  The popover component displays contextual content in an overlay triggered by a
  button. Use for secondary actions, settings, or information that doesn't
  require a full modal.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover.md
---

# Popover

The popover component displays contextual content in an overlay triggered by a button. Use for secondary actions, settings, or information that doesn't require a full modal.

For interactions that need more space or user focus, such as confirmations or complex forms, use [modal](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/modal) instead.

Popovers don't support nesting — opening a second popover while one is already visible closes the first. Popovers open in response to buyer interaction only, not programmatically on page load.

### Support Targets (29)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

#### Use cases

* **Contextual forms:** Collect small amounts of input, like a veteran ID or promo code, without leaving the current view.
* **Size guides:** Display product dimensions or sizing charts in a scrollable overlay anchored to a trigger button.
* **Help content:** Show brief instructions or definitions near the element they describe.
* **Promotional details:** Present active discounts or offers in a compact overlay that buyers can dismiss.

***

## Properties

Configure the following properties on the popover component.

* **blockSize**

  **SizeUnitsOrAuto**

  **Default: 'auto'**

  The block size of the popover (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).

* **id**

  **string**

  A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.

* **inlineSize**

  **SizeUnitsOrAuto**

  **Default: 'auto'**

  The inline size of the popover (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).

* **maxBlockSize**

  **SizeUnitsOrNone**

  **Default: 'none'**

  The maximum block size of the popover. Constrains the popover's height to prevent it from exceeding this value. Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).

* **maxInlineSize**

  **SizeUnitsOrNone**

  **Default: 'none'**

  The maximum inline size of the popover. Constrains the popover's width to prevent it from exceeding this value. Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).

* **minBlockSize**

  **SizeUnits**

  **Default: '0'**

  The minimum block size of the popover. Ensures the popover maintains at least this height. Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).

* **minInlineSize**

  **SizeUnits**

  **Default: '0'**

  The minimum inline size of the popover. Ensures the popover maintains at least this width. Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).

### SizeUnitsOrAuto

Represents size values that can also be set to \`auto\` for automatic sizing. - \`SizeUnits\`: Specific size values in pixels, percentages, or zero for precise control. - \`auto\`: Automatically sizes based on content and layout constraints. Learn more about the \[auto value]\(https://developer.mozilla.org/en-US/docs/Web/CSS/width#auto).

```ts
SizeUnits | "auto"
```

### SizeUnits

Represents size values in pixels, percentages, or zero. - \`\` \`${number}px\` \`\`: Absolute size in pixels for fixed dimensions (such as \`100px\`, \`24px\`). - \`\` \`${number}%\` \`\`: Relative size as a percentage of the parent container (such as \`50%\`, \`100%\`). - \`0\`: Zero size, equivalent to no dimension.

```ts
`${number}px` | `${number}%` | `0`
```

### SizeUnitsOrNone

Represents size values that can also be set to \`none\` to remove the size constraint. - \`SizeUnits\`: Specific size values in pixels, percentages, or zero for precise control. - \`none\`: No size constraint, allowing unlimited growth. Learn more about the \[none value]\(https://developer.mozilla.org/en-US/docs/Web/CSS/max-width#none).

```ts
SizeUnits | "none"
```

### Events

The popover component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **hide**

  **CallbackEventListener\<typeof tagName>**

  A callback fired immediately after the popover is hidden.

* **show**

  **CallbackEventListener\<typeof tagName>**

  A callback fired immediately after the popover is shown.

### CallbackEventListener

A typed event listener for custom element events. The listener receives a \`CallbackEvent\` with the correct \`currentTarget\` type for the associated custom element tag.

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null
```

### CallbackEvent

An event type that narrows the \`currentTarget\` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

***

## Examples

### Verify a veteran ID

Collect buyer input in a popover without leaving the page. This example opens a popover from a button and shows a veteran ID form inside it.

## Verify a veteran ID

![A rendered example of the popover component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/popover-default-DRjK8EYm.png)

## html

```html
<s-button commandFor="popover-veteran-id">Open Popover</s-button>
<s-popover id="popover-veteran-id">
  <s-stack gap="base" padding="base" direction="inline">
    <s-text-field label="Veteran ID"></s-text-field>
    <s-button variant="primary">Validate</s-button>
  </s-stack>
</s-popover>
```

### Show a scrollable size chart

Cap the popover height so long content scrolls instead of expanding the page. This example shows a size chart with `maxBlockSize` set to limit the visible area.

## html

```html
<s-button commandFor="size-guide">Size guide</s-button>


<s-popover id="size-guide" maxBlockSize="250px">
  <s-stack padding="base">
    <s-text type="strong">Size chart (chest measurement)</s-text>
    <s-stack>
      <s-stack direction="inline" justifyContent="space-between">
        <s-text>S</s-text>
        <s-text color="subdued">34-36 in</s-text>
      </s-stack>
      <s-stack direction="inline" justifyContent="space-between">
        <s-text>M</s-text>
        <s-text color="subdued">38-40 in</s-text>
      </s-stack>
      <s-stack direction="inline" justifyContent="space-between">
        <s-text>L</s-text>
        <s-text color="subdued">42-44 in</s-text>
      </s-stack>
      <s-stack direction="inline" justifyContent="space-between">
        <s-text>XL</s-text>
        <s-text color="subdued">46-48 in</s-text>
      </s-stack>
    </s-stack>
  </s-stack>
</s-popover>
```

### Show active promotions

List discount codes in a small overlay near the trigger button. This example shows a popover containing promotion details and a close button.

## html

```html
<s-button commandFor="promo-popover">Promotions</s-button>


<s-popover id="promo-popover">
  <s-stack padding="base" gap="base">
    <s-text type="strong">Active promotions</s-text>
    <s-stack>
      <s-text>SAVE10 — 10% off orders over $50</s-text>
      <s-text>FREESHIP — Free shipping on all orders</s-text>
    </s-stack>
    <s-button variant="secondary" command="--hide" commandFor="promo-popover">
      Close
    </s-button>
  </s-stack>
</s-popover>
```

***

## Best practices

* **Anchor to the trigger:** Position the popover near the element that opens it so buyers understand the relationship between trigger and content.
* **Constrain height for long content:** Set `maxBlockSize` on the popover to cap its height. Wrap overflowing content in a [scroll box](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/scroll-box) to make it scrollable.
* **Keep content focused:** Limit popovers to a single task or piece of information. For complex interactions, use a [modal](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/modal) instead.
* **Avoid placing critical information in a popover:** Popovers are hidden until triggered and close when buyers click outside them, making them unsuitable for essential content or actions that require explicit confirmation.
* **Trigger with a clearly labeled button:** The button that opens the popover should clearly indicate what'll appear when activated.
* **Group related actions:** Contain actions that share a relationship to each other so the popover feels cohesive.

***