---
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: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/overlays/popover
  md: >-
    https://shopify.dev/docs/api/customer-account-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/customer-account-ui-extensions/latest/web-components/overlays/modal) instead.

Popovers open in response to user interaction only, not programmatically on page load.

### Support Targets (24)

### Supported targets

* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Contextual menus**: Display additional options or actions in an overlay triggered by a button.
* **Filter controls**: Present filter options in a popover to save screen space while keeping controls accessible.
* **Extended help**: Show detailed help content or explanations in a popover triggered by an info button.
* **Quick actions**: Provide quick action panels that appear on demand without navigating away from the current view.

***

## 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, TEvent>): 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

### Show a form in a popover

Collect input inline without navigating away from the page. This example presents a text field and submit button inside a popover for verifying a veteran ID.

## Show a form in a popover

![A small floating panel anchored to a trigger element displaying contextual content.](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">Verify veteran status</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>
```

### Display contextual information

Surface supplementary information on demand without cluttering the main view. This example shows shipping details in a popover triggered by a button.

## html

```html
<s-button commandFor="shipping-details">Shipping details</s-button>
<s-popover id="shipping-details">
  <s-stack gap="base" padding="base">
    <s-heading>Standard shipping</s-heading>
    <s-paragraph>Estimated delivery: 5–7 business days</s-paragraph>
    <s-paragraph>Tracking number will be emailed once your order ships.</s-paragraph>
  </s-stack>
</s-popover>
```

### Show a list of actions

Present a set of related actions in a compact overlay. This example shows an action list with options for returns, issue reporting, and support.

## html

```html
<s-button commandFor="order-actions">More actions</s-button>
<s-popover id="order-actions">
  <s-stack gap="none" padding="small">
    <s-clickable padding="small">
      <s-text>Request a return</s-text>
    </s-clickable>
    <s-clickable padding="small">
      <s-text>Report an issue</s-text>
    </s-clickable>
    <s-clickable padding="small">
      <s-text>Contact support</s-text>
    </s-clickable>
  </s-stack>
</s-popover>
```

***

## Best practices

* **Avoid placing critical information in a popover**: Popovers are hidden until triggered, making them unsuitable for essential content that customers need to see immediately.
* **Group related actions**: Contain actions that share a relationship to each other so the popover feels cohesive.
* **Trigger with a clearly labeled button**: The button that opens the popover should clearly indicate what'll appear when activated.

***