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
).
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.
A unique identifier for the Modal
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.
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
.
Anchor to ui-modal instanceui-modal instance
The ui-modal
element provides instance properties and methods to control the Modal.
Add 'show' | 'hide' event listeners.
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.
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.
Hides the save bar element
Remove 'show' | 'hide' event listeners.
Shows the save bar element
A getter/setter that is used to set modal src.
Toggles the save bar element between the showing and hidden states
A getter/setter that is used to set modal variant.
Modal
Preview

Anchor to examplesExamples
Modal options, variations, and events
Anchor to example-modals-with-different-optionsModals with different options
Anchor to example-opening-a-max-size-modalOpening a max size Modal
Modal with max size
Anchor to example-specifying-a-modal-sizeSpecifying a Modal size
Modal with variant
Anchor to example-using-a-form-in-a-modalUsing a form in a Modal
Modal with form
Anchor to example-specifying-a-title-for-the-modalSpecifying a title for the Modal
Modal with title
Anchor to example-adding-primary-and-secondary-actions-to-a-modalAdding primary and secondary actions to a Modal
Modal with primary and secondary actions
Anchor to example-using-a-modal-for-a-destructive-actionUsing a modal for a destructive action
Adding a critical button to a Modal
Opening a max size Modal
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
Subscribing to Show
Event listener
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
Anchor to example-updating-the-modal-variantUpdating 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.
Adding an element
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
Anchor to example-communicating-between-the-modal-and-the-parent-windowCommunicating between the Modal and the parent window
Communicating between the Modal and the parent window
Anchor to example-opening-a-base-modal-within-a-max-src-modalOpening a base modal within a max src modal
This pattern is useful for displaying a dialog or prompt from within a max variant modal.