---
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/latest/polaris-web-components/feedback-and-status-indicators/modal
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/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).

## 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
  ```

```ts
interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
  /**
   * The element that the event listener is attached to.
   */
  currentTarget: HTMLElementTagNameMap[T];
  /**
   * Whether the event bubbles up through the DOM tree.
   */
  bubbles?: boolean;
  /**
   * Whether the event can be canceled.
   */
  cancelable?: boolean;
  /**
   * Whether the event will trigger listeners outside of a shadow root.
   */
  composed?: boolean;
  /**
   * Additional data associated with the event.
   */
  detail?: any;
  /**
   * The current phase of the event flow.
   */
  eventPhase: number;
  /**
   * The element that triggered the event.
   */
  target: HTMLElementTagNameMap[T] | null;
}
```

### 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
  <s-button command="--show" commandFor="modal">
    Open modal
  </s-button>
  <s-modal id="modal" heading="Changes could not be saved">
    Please check your internet connection and try again.
    <s-button slot="primary-action">OK</s-button>
  </s-modal>
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2025-10/modal-default.png)

## 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.