--- title: Popover description: >- The Popover component displays contextual content in a small overlay triggered by user interaction. Use for secondary actions, settings, or information that doesn't require a full modal. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/popover md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/popover.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # Popover The Popover component displays contextual content in a small overlay triggered by user interaction. Use for secondary actions, settings, or information that doesn't require a full modal. The library automatically applies the WAI-ARIA Popover Widget pattern to both the activator and the popover content. 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/2025-07/ui-components/overlays/modal) instead. ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/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/2025-07/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. * **alignment** **Alignment** **Default: 'center'** The alignment of the popover in the axis determined by the position. * **id** **string** A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component. * **maxInlineSize** **MaybeResponsiveConditionalStyle< number | \`${number}%\` | 'fill' >** The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value. * `number`: The size in pixels. * `` `${number}%` ``: The size as a percentage of the parent container's inline size. * `'fill'`: Takes all the available space. Learn more about the [max-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) property. * **minInlineSize** **MaybeResponsiveConditionalStyle< number | \`${number}%\` | 'fill' >** The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value. * `number`: The size in pixels. * `` `${number}%` ``: The size as a percentage of the parent container's inline size. * `'fill'`: Takes all the available space. Learn more about the [min-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) property. * **onClose** **() => void** A callback fired when the popover is closed. * **onOpen** **() => void** A callback fired when the popover is opened. * **padding** **MaybeResponsiveConditionalStyle\>** The padding on all edges of the element, using a shorthand syntax. You can specify one, two, or four values following the CSS shorthand convention. * `T`: A single value applied uniformly to all edges. * `[T, T]`: The first value applies to block-start and block-end, the second to inline-start and inline-end. * `[T, T, T, T]`: Values apply to block-start, inline-end, block-end, and inline-start respectively. * **position** **PopoverPosition** **Default: 'blockStart'** The position of the popover relative to the activator. ### Alignment Controls how content is aligned along the cross axis. - \`'start'\`: Aligns content to the start of the container. - \`'center'\`: Centers content within the container. - \`'end'\`: Aligns content to the end of the container. ```ts 'start' | 'center' | 'end' ``` ### MaybeResponsiveConditionalStyle A type that represents a value that can be a conditional style. The conditions are based on the viewport size. We highly recommend using the \`Style\` helper which simplifies the creation of conditional styles. ```ts T | ConditionalStyle ``` ### ConditionalStyle A conditional style definition that maps one or more conditions to different values. The \`default\` value is used as a fallback when none of the conditions in \`conditionals\` are satisfied. * conditionals An array of conditional values. ```ts ConditionalValue[] ``` * default The default value applied when none of the conditional values specified in \`conditionals\` are met. ```ts T ``` ### ConditionalValue A single conditional branch that pairs a set of conditions with the value to apply when those conditions are met. * conditions The conditions that must be met for the value to be applied. At least one condition must be specified. ```ts AcceptedConditions ``` * value The value that will be applied if the conditions are met. ```ts T ``` ### ViewportSizeCondition A condition that targets layouts based on the inline size (width in horizontal writing modes) of the viewport. * viewportInlineSize The minimum viewport inline size that the condition must match. ```ts { min: T; } ``` ### MaybeShorthandProperty A type that accepts either a single value applied to all edges or a shorthand tuple for per-edge control. - \`T\`: A single value applied uniformly to all edges. - \`\[T, T]\`: The first value applies to block-start and block-end, the second to inline-start and inline-end. - \`\[T, T, T, T]\`: Values apply to block-start, inline-end, block-end, and inline-start respectively. ```ts T | ShorthandProperty ``` ### ShorthandProperty A tuple type that accepts two or four values following the CSS shorthand convention for box edges. - \`\[T, T]\`: The first value applies to block-start and block-end, the second to inline-start and inline-end. - \`\[T, T, T, T]\`: Values apply to block-start, inline-end, block-end, and inline-start respectively. ```ts [T, T] | [T, T, T, T] ``` ### Spacing A keyword that maps to a predefined spacing value from the design system. Use these instead of pixel values to ensure consistent spacing throughout the UI. - \`none\`: No spacing (0px). - \`extraTight\`: The smallest amount of spacing. - \`tight\`: A compact amount of spacing, suitable for tight layouts. - \`base\`: The default spacing, appropriate for most layouts. - \`loose\`: A generous amount of spacing, used to create visual separation. - \`extraLoose\`: The largest amount of spacing. ```ts 'none' | 'extraTight' | 'tight' | 'base' | 'loose' | 'extraLoose' ``` ### PopoverPosition The position of the popover relative to its activator element. - \`'inlineStart'\`: Positions the popover to the left (in LTR layouts) of the activator. - \`'inlineEnd'\`: Positions the popover to the right (in LTR layouts) of the activator. - \`'blockStart'\`: Positions the popover above the activator. - \`'blockEnd'\`: Positions the popover below the activator. ```ts 'inlineStart' | 'inlineEnd' | 'blockStart' | 'blockEnd' ``` *** ## Examples ### Display contextual information Surface supplementary information on demand without cluttering the main view. This example shows payment details in a popover triggered by a pressable element. ## Display contextual information ![A popover displaying contextual payment information.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/popover-default-C47fekuz.png) ## Display contextual information ##### React ```tsx import { reactExtension, Pressable, Popover, View, TextBlock, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( A thoughtful way to pay Tap don’t type Shop Pay remembers your important details, so you can fill carts, not forms. And everything is encrypted so you can speed safely through checkout. } > More info ); } ``` ##### JS ```js import { extension, Pressable, Popover, View, TextBlock, } from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const popoverFragment = root.createFragment(); const popover = root.createComponent(Popover, {}, [ root.createComponent(View, {maxInlineSize: 200, padding: 'base'}, [ root.createComponent(TextBlock, {}, 'A thoughtful way to pay'), root.createComponent(TextBlock, {}, 'Tap don’t type'), root.createComponent( TextBlock, {}, 'Shop Pay remembers your important details, so you can fill carts, not forms. And everything is encrypted so you can speed safely through checkout.', ), ]), ]); popoverFragment.appendChild(popover); const pressable = root.createComponent( Pressable, {overlay: popoverFragment}, 'More info', ); root.appendChild(pressable); }); ``` ### 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 ##### React ```tsx import { reactExtension, Button, Pressable, Popover, View, TextField, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { return ( } > Verify veteran status ); } ``` ##### JS ```js import { extension, Button, Pressable, Popover, View, TextField, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root) => { const popoverFragment = root.createFragment(); const popover = root.createComponent(Popover, {}, [ root.createComponent( View, {maxInlineSize: 280, padding: 'base'}, [ root.createComponent(TextField, {label: 'Veteran ID'}), root.createComponent(Button, {}, 'Verify'), ], ), ]); popoverFragment.appendChild(popover); const pressable = root.createComponent( Pressable, {overlay: popoverFragment}, 'Verify veteran status', ); root.appendChild(pressable); }, ); ``` ### Display a list of actions Present a set of related actions in a compact overlay. This example shows an action list with options for returns, support, and issue reporting. ## Display a list of actions ##### React ```tsx import { reactExtension, Button, Popover, View, BlockStack, Link, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { return ( ); } ``` ##### JS ```js import { extension, Button, Popover, View, BlockStack, Link, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root) => { const popoverFragment = root.createFragment(); const popover = root.createComponent(Popover, {}, [ root.createComponent(View, {padding: 'base'}, [ root.createComponent(BlockStack, {}, [ root.createComponent(Link, {to: '/account/returns'}, 'Start a return'), root.createComponent(Link, {to: '/account/support'}, 'Contact support'), root.createComponent(Link, {to: '/account/report'}, 'Report an issue'), ]), ]), ]); popoverFragment.appendChild(popover); const button = root.createComponent( Button, {overlay: popoverFragment}, 'Order actions', ); root.appendChild(button); }, ); ``` *** ## 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 activator:** The element that opens the popover should clearly indicate what'll appear when activated. *** ## Limitations * Popovers can only be opened by user interaction through an activator component, not programmatically on page load. * The popover position is determined by the activator element and can't be manually overridden. * Content within the popover doesn't scroll automatically; use a `View` component for internal scrolling if needed. ***