---
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-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/overlays/modal
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-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.

## Properties

* **accessibilityLabel**

  **string**

  A label that describes the purpose of the modal. When set, it will be announced to users using assistive technologies and will provide them with more context.

  This overrides the `heading` prop for screen readers.

* **heading**

  **string**

  A title that describes the content of the Modal.

* **id**

  **string**

  A unique identifier for the element.

* **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'**

  Adjust the size of the Modal.

  `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-01/using-polaris-components#event-handling).

* **afterhide**

  **CallbackEventListener\<typeof tagName>**

  Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished.

* **aftershow**

  **CallbackEventListener\<typeof tagName>**

  Callback fired when the overlay is shown **after** any animations to show the overlay have finished.

* **hide**

  **CallbackEventListener\<typeof tagName>**

  Callback fired after the overlay is hidden.

* **show**

  **CallbackEventListener\<typeof tagName>**

  Callback fired after the overlay is shown.

### CallbackEventListener

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null
```

### CallbackEvent

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

## Slots

Learn more about [component slots](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/using-polaris-components#slots).

* **primary-action**

  **HTMLElement**

  The primary action to perform, provided as a button type element.

* **secondary-actions**

  **HTMLElement**

  The secondary actions to perform, provided as button type elements.

## Methods

Learn more about [component methods](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/using-polaris-components#methods).

* **hideOverlay**

  **() => void**

  **required**

  Method to hide an overlay.

Examples

## Preview

![](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/modal-default-B1KXExtT.png)

### Examples

* #### Code

  ##### Default

  ```html
  <s-button command="--show" commandfor="modal-1">Add Product</s-button>
  <s-modal id="modal-1" heading="Return Policy">
    <s-paragraph>
      We have a 30-day return policy, which means you have 30 days after receiving
      your item to request a return.
    </s-paragraph>
    <s-paragraph>
      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.
    </s-paragraph>
    <s-button
      variant="primary"
      command="--hide"
      commandfor="modal-1"
      slot="primary-action"
    >
      Close
    </s-button>
  </s-modal>
  ```