---
title: Modal
description: >-
  Modals are a special type of overlay that shift focus towards a specific
  action/set of information before the main flow can proceed. They must be
  specified inside the `overlay` prop of an activator component (`Button`,
  `Link` or `Pressable`).


  The library automatically applies the [WAI-ARIA Dialog
  pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) to both the
  activator and the modal content.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/modal
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/modal.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Modal

Modals are a special type of overlay that shift focus towards a specific action/set of information before the main flow can proceed. They must be specified inside the `overlay` prop of an activator component (`Button`, `Link` or `Pressable`).

The library automatically applies the [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) to both the activator and the modal content.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* customer-account.​footer.​render-after
* customer-account.​order-index.​announcement.​render
* customer-account.​order-index.​block.​render
* customer-account.​order-status.​announcement.​render
* customer-account.​order-status.​block.​render
* customer-account.​order-status.​cart-line-item.​render-after
* customer-account.​order-status.​cart-line-list.​render-after
* customer-account.​order-status.​customer-information.​render-after
* customer-account.​order-status.​fulfillment-details.​render-after
* customer-account.​order-status.​payment-details.​render-after
* customer-account.​order-status.​return-details.​render-after
* customer-account.​order-status.​unfulfilled-items.​render-after
* customer-account.​order.​action.​menu-item.​render
* customer-account.​order.​action.​render
* customer-account.​order.​page.​render
* customer-account.​page.​render
* customer-account.​profile.​addresses.​render-after
* customer-account.​profile.​announcement.​render
* customer-account.​profile.​block.​render
* customer-account.​profile.​company-details.​render-after
* customer-account.​profile.​company-location-addresses.​render-after
* customer-account.​profile.​company-location-payment.​render-after
* customer-account.​profile.​company-location-staff.​render-after
* customer-account.​profile.​payment.​render-after

## ModalProps

* **accessibilityLabel**

  **string**

  A label that describes the purpose of the modal, announced by screen readers. If not set, it will use the value of `title`.

* **id**

  **string**

  A unique identifier for the modal. When no `id` is set, a globally unique value will be used instead.

* **onClose**

  **() => void**

  A callback fired when the modal is closed. This is triggered when the close button, the backdrop, or the `escape` key are pressed.

* **onOpen**

  **() => void**

  A callback fired when the modal is opened. This is called at the beginning of the transition that opens the modal.

* **padding**

  **boolean**

  Whether to add default spacing around both the header (which holds the `title`) and the content of the modal.

* **primaryAction**

  **RemoteFragment**

  The primary action to perform, provided as a Button component. Only one button can be rendered.

* **secondaryActions**

  **RemoteFragment**

  The secondary actions to perform, provided as Button components. Only one button can be rendered.

* **size**

  **'small' | 'auto' | 'large' | 'max'**

  **Default: 'auto'**

  Adjust the size of the modal.

  * `'small'`: A compact modal for simple confirmations or short messages.
  * `'auto'`: Automatically sizes the modal based on its content.
  * `'large'`: A large modal for complex content or forms.
  * `'max'`: Expands the modal to its maximum size, on both the horizontal and vertical axes.

* **title**

  **string**

  A title rendered at the top of the modal.

Examples

## Preview

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

### Examples

* #### Basic Modal

  ##### React

  ```tsx
  import {
    reactExtension,
    useApi,
    Button,
    Link,
    Modal,
    TextBlock,
  } from '@shopify/ui-extensions-react/customer-account';

  export default reactExtension(
    'customer-account.page.render',
    () => <Extension />,
  );

  function Extension() {
    const {ui} = useApi();

    return (
      <Link
        overlay={
          <Modal
            id="my-modal"
            padding
            title="Return policy"
          >
            <TextBlock>
              We have a 30-day return policy, which
              means you have 30 days after receiving
              your item to request a return.
            </TextBlock>
            <TextBlock>
              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.
            </TextBlock>
            <Button
              onPress={() =>
                ui.overlay.close('my-modal')
              }
            >
              Close
            </Button>
          </Modal>
        }
      >
        Return policy
      </Link>
    );
  }
  ```

  ##### JS

  ```js
  import {
    extension,
    Button,
    Link,
    Modal,
    TextBlock,
  } from '@shopify/ui-extensions/customer-account';

  export default extension('customer-account.page.render', (root, {ui}) => {
    const modalFragment = root.createFragment();
    const modal = root.createComponent(
      Modal,
      {id: 'my-modal', title: 'Return policy', padding: true},
      [
        root.createComponent(
          TextBlock,
          undefined,
          'We have a 30-day return policy, which means you have 30 days after receiving your item to request a return.',
        ),
        root.createComponent(
          TextBlock,
          undefined,
          '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.',
        ),
        root.createComponent(
          Button,
          {
            onPress() {
              ui.overlay.close('my-modal');
            },
          },
          'Close',
        ),
      ],
    );
    modalFragment.appendChild(modal);
    const link = root.createComponent(
      Link,
      {overlay: modalFragment},
      'Return policy',
    );

    root.appendChild(link);
  });
  ```

## Best Practices

Use modals if:

* The information needed to be shown is not critical in completing the checkout process and information cannot be condensed into one sentence.

* The information the buyer is entering requires less than two rows of input fields.

* The information the buyer is entering is not reliant on information on the page (which is underneath the modal and not visible to them).

## Related

[API - Ui](ui)