---
title: ui-modal
description: |-
  The Modal API allows you to display an overlay that prevents interaction with the rest of the app until dismissed.

   It is used by customizing your Modal content with the `ui-modal` element and then opening it with the `show()` instance method or the `shopify.modal.show('modal-id')` API.
api_name: app-bridge-library
source_url:
  html: https://shopify.dev/docs/api/app-bridge-library/web-components/ui-modal
  md: https://shopify.dev/docs/api/app-bridge-library/web-components/ui-modal.md
---

# ui-modal

The Modal API allows you to display an overlay that prevents interaction with the rest of the app until dismissed.

It is used by customizing your Modal content with the `ui-modal` element and then opening it with the `show()` instance method or the `shopify.modal.show('modal-id')` API.

## ui-modal element

The `ui-modal` element is available for use in your app. It configures a Modal to display in the Shopify Admin.

The content you provide can be simple HTML elements or a `src` URL that will be loaded. When adding custom content, you can only provide a single parent element (commonly a `div` or `form`).

* children

  HTMLCollection & UITitleBarAttributes

  The content to display within a Modal. You can provide a single HTML element with children and the [ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar) element to configure the Modal title bar.

* id

  string

  A unique identifier for the Modal

* src

  string

  The URL of the content to display within a Modal. If provided, the Modal will display the content from the provided URL and any children other than the [ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar) and [ui-save-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar) elements will be ignored.

* variant

  'small' | 'base' | 'large' | 'max'

  Default: "base"

  The size of the modal.

  Before the Modal is shown, this can be changed to any of the provided values. After the Modal is shown, this can can only be changed between `small`, `base`, and `large`.

### UITitleBarAttributes

* children

  The children of the title bar.

  ```ts
  any
  ```

* title

  The title of the title bar. Can also be set via \<code>document.title\</code>.

  ```ts
  string
  ```

```ts
export interface UITitleBarAttributes extends _UITitleBarAttributes {
  children?: any;
}
```

## ui-modal instance

The `ui-modal` element provides instance properties and methods to control the Modal.

* addEventListener

  (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void

  Add 'show' | 'hide' event listeners.

* content

  HTMLElement

  A getter/setter that is used to get the DOM content of the modal element and update the content after the modal has been opened.

* contentWindow

  Window | null

  A getter that is used to get the Window object of the modal iframe when the modal is used with a `src` attribute. This can only be accessed when the modal is open, so it is recommended to use `await modal.show()` before accessing this property.

* hide

  () => Promise\<void>

  Hides the save bar element

* removeEventListener

  (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void

  Remove 'show' | 'hide' event listeners.

* show

  () => Promise\<void>

  Shows the save bar element

* src

  string

  A getter/setter that is used to set modal src.

* toggle

  () => Promise\<void>

  Toggles the save bar element between the showing and hidden states

* variant

  Variant

  A getter/setter that is used to set modal variant.

### Variant

```ts
'small' | 'base' | 'large' | 'max'
```

### Examples

* #### Modal

  ##### Modal

  ```html
  <ui-modal id="my-modal">
    <p>Message</p>
    <ui-title-bar title="Title">
      <button variant="primary">Label</button>
      <button onclick="document.getElementById('my-modal').hide()">Label</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/app-bridge-library/modal.png)

## Examples

Modal options, variations, and events

### Modals with different options

Opening a max size Modal

Modal with max size

Specifying a Modal size

Modal with variant

Using a form in a Modal

Modal with form

Specifying a title for the Modal

Modal with title

Adding primary and secondary actions to a Modal

Modal with primary and secondary actions

Using a modal for a destructive action

Adding a critical button to a Modal

### Examples

* #### Opening a max size Modal

  ##### Description

  Modal with max size

  ##### Default

  ```html
  <ui-modal id="my-modal" variant="max">
    <div></div>
    <ui-title-bar>
      <button variant="primary">Primary action</button>
      <button>Secondary action</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

* #### Specifying a Modal size

  ##### Description

  Modal with variant

  ##### Default

  ```html
  <ui-modal id="my-modal" variant="large">
    <p>Hello, World!</p>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

* #### Using a form in a Modal

  ##### Description

  Modal with form

  ##### Default

  ```html
  <ui-modal id="my-modal" variant="max">
    <form data-save-bar>
      <label>
        Name:
        <input name="submitted-name" autocomplete="name" />
      </label>
      <button>Save</button>
    </form>
    <ui-title-bar>
      <button variant="primary">Save</button>
      <button>Cancel</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

* #### Specifying a title for the Modal

  ##### Description

  Modal with title

  ##### Default

  ```html
  <ui-modal id="my-modal">
    <p>Hello, World!</p>
    <ui-title-bar title="My Modal"></ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

* #### Adding primary and secondary actions to a Modal

  ##### Description

  Modal with primary and secondary actions

  ##### Default

  ```html
  <ui-modal id="my-modal">
    <p>Hello, World!</p>
    <ui-title-bar>
      <button variant="primary" onclick="console.log('Saving')">Save</button>
      <button onclick="console.log('Cancelling')">Cancel</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

* #### Using a modal for a destructive action

  ##### Description

  Adding a critical button to a Modal

  ##### Default

  ```html
  <ui-modal id="my-modal">
    <p>If you delete this resource, it can't be undone.</p>
    <ui-title-bar title="Delete this resource">
      <button variant="primary" tone="critical" onclick="console.log('Deleting')">
        Delete
      </button>
      <button onclick="console.log('Cancelling')">Cancel</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/app-bridge-library/modal-max.png)

### Modal events

Subscribing to Show

Subscribing to the `show` event which is emitted when the Modal is shown

Subscribing to Hide

Subscribing to the `hide` event which is emitted when the Modal is closed

### Examples

* #### Subscribing to Show

  ##### Description

  Subscribing to the \`show\` event which is emitted when the Modal is shown

  ##### Event listener

  ```html
  <ui-modal id="my-modal">
    <p>Message</p>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>

  <script>
    document.getElementById('my-modal').addEventListener('show', () => {
      console.log('Modal is showing');
    });
  </script>
  ```

* #### Subscribing to Hide

  ##### Description

  Subscribing to the \`hide\` event which is emitted when the Modal is closed

  ##### Event listener

  ```html
  <ui-modal id="my-modal">
    <div>
      <button onclick="document.getElementById('my-modal').hide()">
        Hide Modal
      </button>
    </div>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Show Modal</button>

  <script>
    document.getElementById('my-modal').addEventListener('hide', () => {
      console.log('Modal is hiding');
    });
  </script>
  ```

### Updating the Modal once it is open

Adding an element

Adding an element to the Modal after it is opened

Updating the Modal variant

Updating the Modal variant after it is opened.

When the Modal is open, it can only be changed between the `small`, `base`, and `large` variants.

### Examples

* #### Adding an element

  ##### Description

  Adding an element to the Modal after it is opened

  ##### Default

  ```html
  <ui-modal id="my-modal">
    <div>
      <p>Message</p>
      <button id="add-content">Add element</button>
    </div>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>

  <script>
    const button = document.getElementById('add-content');
    button.addEventListener('click', () => {
      const p = document.createElement('p');
      p.textContent = 'Lorem ipsum';

      const modal = document.getElementById('my-modal');
      modal.content.appendChild(p);
    });
  </script>
  ```

* #### Updating the Modal variant

  ##### Description

  Updating the Modal variant after it is opened. When the Modal is open, it can only be changed between the \`small\`, \`base\`, and \`large\` variants.

  ##### Default

  ```html
  <ui-modal id="my-modal">
    <div>
      <p>Message</p>
      <button id="add-content">Add element</button>
    </div>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>

  <script>
    const button = document.getElementById('add-content');
    button.addEventListener('click', () => {
      const p = document.createElement('p');
      p.textContent = 'Lorem ipsum';

      const modal = document.getElementById('my-modal');
      modal.content.appendChild(p);
    });
  </script>
  ```

### Using a src URL to load content

Loading content from a URL

Loading content from a URL

Communicating between the Modal and the parent window

Communicating between the Modal and the parent window

Opening a base modal within a max src modal

This pattern is useful for displaying a dialog or prompt from within a max variant modal.

### Examples

* #### Loading content from a URL

  ##### Description

  Loading content from a URL

  ##### Default

  ```html
  // main app
  <ui-modal id="my-modal" src="/my-route">
    <ui-title-bar title="Title">
      <button variant="primary">Label</button>
      <button onclick="document.getElementById('my-modal').hide()">Label</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>

  // my-route.html
  <!DOCTYPE html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
      <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
    </head>

    <body>
      <h1>My separate route</h1>
    </body>
  </html>
  ```

* #### Communicating between the Modal and the parent window

  ##### Description

  Communicating between the Modal and the parent window

  ##### Default

  ```html
  // main app
  <script>
    window.addEventListener('message', (ev) => {
      console.log('Message received in main app:', ev.data);
    });

    window.addEventListener('load', async () => {
      const modal = document.getElementById('src-modal');
      await modal.show();
      modal.contentWindow.postMessage('Hello from the main app', location.origin);
    });
  </script>

  <ui-modal id="my-modal" src="/my-route">
    <ui-title-bar title="Title">
      <button variant="primary">Label</button>
      <button onclick="document.getElementById('my-modal').hide()">Label</button>
    </ui-title-bar>
  </ui-modal>

  <button onclick="document.getElementById('my-modal').show()">Open Modal</button>

  // my-route.html
  <!DOCTYPE html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
      <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
    </head>

    <body>
      <button
        onclick="window.opener.postMessage('Hello from the modal', location.origin)"
      >
        Send message
      </button>
      <script>
        window.addEventListener('message', (ev) => {
          console.log('Message received in modal:', ev.data);
        });
      </script>
    </body>
  </html>
  ```

* #### Opening a base modal within a max src modal

  ##### Description

  This pattern is useful for displaying a dialog or prompt from within a max variant modal.

  ##### Default

  ```html
  // main app
  <ui-modal src="/my-route" variant="max" id="my-modal"></ui-modal>
  <button onclick="shopify.modal.show('my-modal')">Open</button>
  <ui-modal id="my-nested-modal">
    <p>Message</p>
  </ui-modal>

  // my-route.html
  <!DOCTYPE html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
      <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
    </head>
    <body>
      <button onclick="window.opener.shopify.modal.show('my-nested-modal')">Open</button>
    </body>
  </html>
  ```

## Related

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/app-bridge-library/apis/modal)

[APIsModal](https://shopify.dev/docs/api/app-bridge-library/apis/modal)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/app-bridge-library/react-components/modal-component)

[React ComponentsModal Component](https://shopify.dev/docs/api/app-bridge-library/react-components/modal-component)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar)

[Web Componentsui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar)

[Web Componentsui-save-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar)