Skip to main content

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.

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

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.

string

A unique identifier for the Modal

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.

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

Was this section helpful?

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

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

Add 'show' | 'hide' event listeners.

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.

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.

() => Promise<void>

Hides the save bar element

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

Remove 'show' | 'hide' event listeners.

() => Promise<void>

Shows the save bar element

string

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

() => Promise<void>

Toggles the save bar element between the showing and hidden states

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

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>

Preview

Modal options, variations, and events

Was this section helpful?

Opening a max size Modal

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

Preview

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

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>

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

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>

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

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