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.

Anchor to ui-modal elementui-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).

Anchor to children children HTMLCollection &: The content to display within a Modal. You can provide a single HTML element with children and the ui-title-bar element to configure the Modal title bar.
Anchor to id id string: A unique identifier for the Modal
Anchor to src 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 and ui-save-bar elements will be ignored.
Anchor to variant 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.

_UIModalAttributes

children
The content to display within a Modal. You can provide a single HTML element with children and the [ui-title-bar](/docs/api/app-bridge-library/web-components/ui-title-bar) element to configure the Modal title bar.
```
HTMLCollection & UITitleBarAttributes
```
id
A unique identifier for the Modal
```
string
```
src
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](/docs/api/app-bridge-library/web-components/ui-title-bar) and [ui-save-bar](/docs/api/app-bridge-library/web-components/ui-save-bar) elements will be ignored.
```
string
```
variant
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`.
```
'small' | 'base' | 'large' | 'max'
```

export interface _UIModalAttributes {
  /**
   * A unique identifier for the Modal
   */
  id?: string;
  /**
   * 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`.
   *
   * @defaultValue "base"
   */
  variant?: 'small' | 'base' | 'large' | 'max';
  /**
   * 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](/docs/api/app-bridge-library/web-components/ui-title-bar)
   * and [ui-save-bar](/docs/api/app-bridge-library/web-components/ui-save-bar) elements will be ignored.
   */
  src?: string;
  /**
   * The content to display within a Modal.
   * You can provide a single HTML element with children
   * and the [ui-title-bar](/docs/api/app-bridge-library/web-components/ui-title-bar)
   * element to configure the Modal title bar.
   */
  children?: HTMLCollection & UITitleBarAttributes;
}

UITitleBarAttributes

children
The children of the title bar.
```
any
```
title
The title of the title bar. Can also be set via <code>document.title</code>.
```
string
```

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

Was this section helpful?

Anchor to ui-modal instanceui-modal instance

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

Anchor to addEventListener addEventListener (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void: Add 'show' | 'hide' event listeners.
Anchor to content 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.
Anchor to contentWindow 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.
Anchor to hide hide () => Promise<void>: Hides the save bar element
Anchor to removeEventListener removeEventListener (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void: Remove 'show' | 'hide' event listeners.
Anchor to show show () => Promise<void>: Shows the save bar element
Anchor to src src string: A getter/setter that is used to set modal src.
Anchor to toggle toggle () => Promise<void>: Toggles the save bar element between the showing and hidden states
Anchor to variant variant: A getter/setter that is used to set modal variant.

_UIModalElement

addEventListener

Add 'show' | 'hide' event listeners.

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

content
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.
```
HTMLElement
```
contentWindow
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.
```
Window | null
```
hide
Hides the save bar element
```
() => Promise<void>
```

removeEventListener

Remove 'show' | 'hide' event listeners.

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

show
Shows the save bar element
```
() => Promise<void>
```
src
A getter/setter that is used to set modal src.
```
string
```
toggle
Toggles the save bar element between the showing and hidden states
```
() => Promise<void>
```
variant
A getter/setter that is used to set modal variant.
```
Variant
```

interface _UIModalElement {
  /**
   * A getter/setter that is used to set modal variant.
   */
  variant?: Variant;
  /**
   * 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.
   */
  content?: HTMLElement;
  /**
   * A getter/setter that is used to set modal src.
   */
  src?: string;
  /**
   * 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.
   */
  readonly contentWindow?: Window | null;
  /**
   * Shows the save bar element
   */
  show?(): Promise<void>;
  /**
   * Hides the save bar element
   */
  hide?(): Promise<void>;
  /**
   * Toggles the save bar element between the showing and hidden states
   */
  toggle?(): Promise<void>;
  /**
   * Add 'show' | 'hide' event listeners.
   * @param type An event name
   * @param listener A callback triggered when the event name happens
   */
  addEventListener?(
    type: 'show' | 'hide',
    listener: EventListenerOrEventListenerObject,
  ): void;
  /**
   * Remove 'show' | 'hide' event listeners.
   * @param type An event name
   * @param listener A callback to be removed
   */
  removeEventListener?(
    type: 'show' | 'hide',
    listener: EventListenerOrEventListenerObject,
  ): void;
}

Variant

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

Was this section helpful?

Modal

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

examples

Modal

<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

Anchor to examplesExamples

Modal options, variations, and events

Anchor to example-modals-with-different-optionsModals with different options

Was this section helpful?

Opening a max size Modal

<ui-modal id="my-modal" variant="max">

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

examples

Opening a max size Modal

description

Modal with max size

<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

<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

<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

<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

<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

<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

Anchor to example-modal-eventsModal events

Anchor to example-subscribing-to-showSubscribing to Show

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

Anchor to example-subscribing-to-hideSubscribing to Hide

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

Was this section helpful?

Subscribing to Show

Event listener

<ui-modal id="my-modal">

<p>Message</p>

</ui-modal>

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

document.getElementById('my-modal').addEventListener('show', () => {

console.log('Modal is showing');

});

</script>

examples

Subscribing to Show

description

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

Event listener

<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

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

Anchor to example-updating-the-modal-once-it-is-openUpdating the Modal once it is open

Anchor to example-adding-an-elementAdding an element

Adding an element to the Modal after it is opened

Was this section helpful?

Adding an element

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

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>

examples

Adding an element

description

Adding an element to the Modal after it is opened

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

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

Anchor to example-using-a-src-url-to-load-contentUsing a src URL to load content

Anchor to example-loading-content-from-a-urlLoading content from a URL

Loading content from a URL

Was this section helpful?

Loading content from a URL

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

</head>

<body>

<h1>My separate route</h1>

</body>

</html>

examples

Loading content from a URL

description

Loading content from a URL

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

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

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

Anchor to relatedRelated

APIsModal

React ComponentsModal Component

Web Componentsui-title-bar

Web Componentsui-save-bar