---
title: Modal
description: >-
The modal component displays content in an overlay that requires merchant
attention. Use modals to present critical information, confirmations, or
focused tasks while maintaining page context.
Modals block interaction with the underlying interface until the merchant
resolves the modal content.
Modals don't automatically handle state management or persistence, so manage
visibility and lifecycle programmatically through
[events](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/feedback-and-status-indicators/modal#events).
api_version: 2025-10
api_name: pos-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/feedback-and-status-indicators/modal
md: >-
https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/feedback-and-status-indicators/modal.md
---
# Modal
The modal component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context.
Modals block interaction with the underlying interface until the merchant resolves the modal content.
Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/feedback-and-status-indicators/modal#events).
### Support Targets (16)
### Supported targets
* [pos.cart.line-item-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/cart-details#cart-details-action-modal-)
* [pos.customer-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/customer-details#customer-details-action-modal-)
* [pos.customer-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/customer-details#customer-details-targets)
* [pos.draft-order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/draft-order-details#draft-order-details-action-modal-)
* [pos.draft-order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/draft-order-details#draft-order-details-targets)
* [pos.exchange.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-exchange#post-exchange-action-modal-)
* [pos.exchange.post.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-exchange#post-exchange-targets)
* [pos.home.modal.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/home-screen#home-screen-action-modal-)
* [pos.order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/order-details#order-details-action-modal-)
* [pos.order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/order-details#order-details-targets)
* [pos.product-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/product-details#product-details-action-modal-)
* [pos.product-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/product-details#product-details-targets)
* [pos.purchase.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-purchase#post-purchase-action-modal-)
* [pos.purchase.post.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-purchase#post-purchase-targets)
* [pos.return.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-return#post-return-action-modal-)
* [pos.return.post.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-return#post-return-targets)
#### Use cases
* **Confirmations:** Display confirmation dialogs for critical actions like refunds or data deletion.
* **Detailed views:** Present information requiring focused attention, like error details or status.
* **Data collection:** Collect input through forms or settings panels without navigating away.
* **Progress indicators:** Show progress for long-running operations like imports or sync.
## Examples
### Display content in a modal overlay
Display focused content in an overlay using a modal component that requires merchant attention. This example shows a basic modal with header, content area, and action buttons.
## Display content in a modal overlay
### Examples
* #### Display content in a modal overlay
##### Description
Display focused content in an overlay using a modal component that requires merchant attention. This example shows a basic modal with header, content area, and action buttons.
##### Default
```html
Open modal
Please check your internet connection and try again.
OK
```
## Properties
Configure the following properties on the modal component.
* **heading**
**string**
A title that describes the content of the section. If omitted and no secondary actions are provided, the section will be rendered without a header.
* **id**
**string**
A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.
## Slots
The modal component supports slots for additional content placement within the modal. Learn more about [using slots](https://shopify.dev/docs/api/polaris/using-polaris-web-components#slots).
* **primary-action**
**HTMLElement**
The primary action button displayed in the modal. The tone of the button is used to define the tone of the modal. If omitted, the modal will default to an `'info'` tone, and show an OK button, translated according to the user's locale.
* **secondary-actions**
**HTMLElement**
The secondary action buttons displayed in the modal. Use this slot to provide alternative actions or cancel options that give users flexibility in how they respond to the modal.
## Events
The modal 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**
**(event: CallbackEvent<"s-modal">) => void**
The callback when the modal is hidden. Use this event to perform cleanup tasks, update application state, or trigger other actions when the modal is dismissed or closed.
* **show**
**(event: CallbackEvent<"s-modal">) => void**
The callback when the modal is shown. Use this event to initialize modal content, focus specific elements, or perform setup tasks when the modal becomes visible.
### CallbackEvent
Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.
* bubbles
Whether the event bubbles up through the DOM tree.
```ts
boolean
```
* cancelable
Whether the event can be canceled.
```ts
boolean
```
* composed
Whether the event will trigger listeners outside of a shadow root.
```ts
boolean
```
* currentTarget
The element that the event listener is attached to.
```ts
HTMLElementTagNameMap[T]
```
* detail
Additional data associated with the event.
```ts
any
```
* eventPhase
The current phase of the event flow.
```ts
number
```
* target
The element that triggered the event.
```ts
HTMLElementTagNameMap[T] | null
```
## Best practices
* **Use for focused interactions:** Reserve modals for confirmations, critical information, or tasks requiring immediate attention.
* **Write clear headings:** Use concise titles that communicate the purpose or action.
* **Choose appropriate button tones:** The primary-action button's `tone` determines the modal's overall tone. Use `critical` for destructive actions, `success` for confirmations.
* **Include secondary actions:** Provide options like "Cancel" or "Go Back" to give merchants flexibility.
* **Keep content focused:** Limit to essential information and actions. For complex workflows, break into multiple steps.
## Limitations
Multiple modals can't be displayed simultaneously—showing a new modal while another is visible may cause unexpected behavior or poor user experience.