--- title: Modal description: >- Displays content in an overlay. Use to create a distraction-free experience such as a confirmation dialog or a settings panel. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/modal md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/modal.md --- # Modal Displays content in an overlay. Use to create a distraction-free experience such as a confirmation dialog or a settings panel. ### Support Targets (29) ### Supported targets * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## Properties * **accessibilityLabel** **string** A label that describes the purpose of the modal, announced by assistive technologies. When set, screen readers will use this label instead of the `heading` to describe the modal. * **heading** **string** A title that describes the content of the modal. * **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. * **padding** **'base' | 'none'** **Default: 'base'** Adjust the padding around the modal content. * `base`: Applies padding that is appropriate for the element. * `none`: Removes all padding from the element. This can be useful when elements inside the modal need to span to the edge of the modal. For example, a full-width image. In this case, rely on box with a padding of `base` to bring back the desired padding for the rest of the content. * **size** **'small' | 'large' | 'base' | 'small-100' | 'large-100' | 'max'** **Default: 'base'** The size of the modal. * `'base'`: The default size, suitable for most use cases. * `'small'`: A compact modal for simple confirmations or short messages. * `'small-100'`: The smallest modal size. * `'large'`: A large modal for complex content or forms. * `'large-100'`: The largest fixed-size modal, providing maximum room for content. * `'max'`: Expands the modal to its maximum size as defined by the host application, on both the horizontal and vertical axes. ## Events Learn more about [registering events](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#event-handling). * **afterhide** **CallbackEventListener\** A callback fired when the modal is hidden, after any hide animations have completed. * **aftershow** **CallbackEventListener\** A callback fired when the modal is shown, after any show animations have completed. * **hide** **CallbackEventListener\** A callback fired immediately after the modal is hidden. * **show** **CallbackEventListener\** A callback fired immediately after the modal 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 & 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]; } ``` ## Slots Learn more about [component slots](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#slots). * **primary-action** **HTMLElement** The main action button displayed in the modal footer, representing the primary action users should take. Only accepts a single button component. * **secondary-actions** **HTMLElement** Additional action buttons displayed in the modal footer, providing alternative or supporting actions. ## Methods Learn more about [component methods](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#methods). * **hideOverlay** **() => void** **required** A method to programmatically hide the overlay and run any associated hide animations. Examples ## Preview ![](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/modal-default-B1KXExtT.png) ### Examples * #### Code ##### Default ```html Add Product We have a 30-day return policy, which means you have 30 days after receiving your item to request a return. To be eligible for a return, your item must be in the same condition that you received it, unworn or unused, with tags, and in its original packaging. You’ll also need the receipt or proof of purchase. Close ```