---
title: Modal
description: >-
  The modal component 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/2026-01/web-components/overlays/modal
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/overlays/modal.md
---

# Modal

The modal component displays content in an overlay. Use to create a distraction-free experience such as a confirmation dialog or a settings panel.

Modals support a heading, scrollable body content, and action slots for primary and secondary buttons. For contextual content that doesn't require full focus, use [popover](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/overlays/popover) instead.

Only one modal is visible at a time — triggering a second modal while another is open replaces the first without stacking. Modals open in response to buyer interaction only, not programmatically on page load.

### Support Targets (29)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#checkout-cart-line-list-)
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/order-summary#thank-you-cart-line-list-)
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/header#header-target)

#### Use cases

* **Confirmation dialogs:** Ask buyers to confirm destructive actions like cancelling an order or removing an item before proceeding.
* **Informational overlays:** Display return policies, terms of service, or warranty details without navigating away from checkout.
* **Form collection:** Collect structured input such as gift messages, custom notes, or shipping preferences inside a focused overlay.
* **Settings panels:** Present configuration options like notification preferences or delivery instructions in an isolated context.

***

## Properties

Configure the following properties on the modal component.

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

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

* **afterhide**

  **CallbackEventListener\<typeof tagName>**

  A callback fired when the modal is hidden, after any hide animations have completed.

* **aftershow**

  **CallbackEventListener\<typeof tagName>**

  A callback fired when the modal is shown, after any show animations have completed.

* **hide**

  **CallbackEventListener\<typeof tagName>**

  A callback fired immediately after the modal is hidden.

* **show**

  **CallbackEventListener\<typeof tagName>**

  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<TTagName, Event> & 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

The modal component supports slots for additional content placement within the component. Learn more about [using slots](https://shopify.dev/docs/api/polaris/using-polaris-web-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

The modal component exposes methods for programmatic control. Learn more about [using methods](https://shopify.dev/docs/api/polaris/using-polaris-web-components#methods).

* **hideOverlay**

  **() => void**

  **required**

  A method to programmatically hide the overlay and run any associated hide animations.

***

## Examples

### Display a return policy

Show store policy details without leaving the checkout page. This example opens a modal with return policy text and a close button.

## Display a return policy

![A rendered example of the modal component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/modal-default-B1KXExtT.png)

## html

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

### Confirm a destructive action

Ask buyers to confirm before cancelling an order or removing an item. This example uses a small modal with a warning, a `critical`-toned confirm button, and a cancel button.

## html

```html
<s-stack gap="base">
  <s-button tone="critical" command="--show" commandFor="delete-modal">
    Cancel order
  </s-button>


  <s-modal id="delete-modal" heading="Cancel this order?" size="small">
    <s-stack>
      <s-text>Are you sure you want to cancel order #1042?</s-text>
      <s-text tone="warning">
        This will release all reserved inventory. This action cannot be undone.
      </s-text>
    </s-stack>


    <s-button
      slot="primary-action"
      variant="primary"
      tone="critical"
      command="--hide"
      commandFor="delete-modal"
    >
      Cancel order
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      command="--hide"
      commandFor="delete-modal"
    >
      Keep order
    </s-button>
  </s-modal>
</s-stack>
```

### Collect input with a form

Collect buyer input without leaving the checkout page. This example shows a gift message form with text fields, a text area, a checkbox, and save and cancel buttons.

## html

```html
<s-stack gap="base">
  <s-button command="--show" commandFor="gift-modal">
    Add gift message
  </s-button>


  <s-modal id="gift-modal" heading="Gift message" size="base">
    <s-stack>
      <s-text-field label="Recipient name" required></s-text-field>
      <s-text-area label="Message" rows="3" maxLength="200"></s-text-area>
      <s-checkbox label="Include gift receipt"></s-checkbox>
    </s-stack>


    <s-button
      slot="primary-action"
      variant="primary"
      command="--hide"
      commandFor="gift-modal"
    >
      Save message
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      command="--hide"
      commandFor="gift-modal"
    >
      Cancel
    </s-button>
  </s-modal>
</s-stack>
```

***

## Best practices

* **Use for focused, specific tasks:** Modals work best when buyers need to make a decision or acknowledge critical information. Don't use them for contextual tools or actions that could happen on the page directly.
* **Write clear headings:** Use concise titles that communicate the purpose of the modal, such as "Cancel this order?" or "Gift message."
* **Size appropriately:** Use `small` for simple confirmations and `base` for forms or longer content. Avoid oversized modals for short messages.
* **Include a prominent call to action:** Every modal should have a clear primary action so buyers know what to do next. Always include a secondary action or dismiss mechanism so buyers aren't trapped in the overlay.
* **Use critical tone for destructive actions:** Set `tone="critical"` on the primary button when the action is irreversible, like cancelling an order. Describe what'll happen in the modal body before the buyer confirms.
* **Use specific action verbs:** Label buttons with clear verbs like "Cancel order", "Save", or "Continue" rather than vague terms like "Yes", "OK", or "Submit."
* **Don't nest modals:** Avoid launching one modal from another. If the workflow requires multiple steps, reconsider the design.
* **Use sparingly:** Don't create unnecessary interruptions. Modals should be a last resort for important decisions during checkout.

***