Modals are overlays that prevent merchants from interacting with the rest of the app until a specific action is taken.
Modals can be disruptive because they require merchants to take an action before they can continue interacting with the rest of Shopify. As such, modals should be used thoughtfully and sparingly.
Modal action set allows you to open two types of modal: message and iframe. Message modals support only plain text content. Iframe modals allow you to fully customize the modal contents.
Create an app and import the
Modal module from
@shopify/app-bridge/actions. Note that we'll be referring to this sample application throughout the examples below.
Create a message modal
Create a message modal using the
message option. Message modals support plain text content of any length using the
Create an iframe modal
Create an iframe modal by passing the
url option. If the
url option is present, then the
message option will be ignored.
Create an iframe modal with an absolute URL
Create an iframe modal with a relative path
A relative path iframe sets the URL relative to your app root.
If your app’s root URL was
https://myapp.com, then the example above would open a modal at
Open and close a modal
Open and close the modal by dispatching the
Add footer buttons
You can add buttons to the modal footer. All modals support one primary button and multiple secondary buttons. To learn more about buttons, refer to Button.
You can subscribe to modal actions by calling
subscribe. This returns a function that you can call to unsubscribe from the action:
All action sets in App Bridge support the same subscribe API. The modal footer buttons also return an unsubscribe function.
Unsubscribe from all
You can call
unsubscribe to remove all subscriptions on the modal and its children (including buttons):
Unsubscribe from modal actions only
You can call
false to remove only modal subscriptions while leaving child subscriptions intact. For example, you might want to unsubscribe from the modal but keep button listeners so that the buttons can be reused in a different modal.
You can call the
set method with partial modal options to update the options of an existing modal. This automatically triggers the
update action on the modal and merges the given options with the existing options.
Update footer buttons
You can update buttons attached to a modal's footer. Any updates made to the modal's footer buttons automatically trigger an
update action on the modal:
Set modal size
By default, modals have a fixed size of
Small. You can customize the size of a modal by passing in a different
There are 3 values for
Set modal size automatically
setupModalAutoSizing utility allows your iframe modal to update its height to fit the page content.
In your main app, open an iframe modal:
Inside the modal page, import the
setupModalAutoSizing utility to enable auto sizing:
padding styles on the
<body> element of your modal page, as these will interfere with automatic modal sizing. As a workaround, set these styles on a wrapper element instead.
If you are using Shopify Polaris, be aware that it applies
height: 100% to the
<body> element by default. You will need to override this style on your modal page.
Communicate with the parent page
It’s often useful for a modal to be able to communicate with its parent page. You can use the
DATA action to send messages between an iframe modal and its parent app.
To send data from a modal, dispatch a
Modal.Action.DATA action from your modal:
In your app, subscribe to
To send data from the app to the modal, complete the steps in reverse: subscribe to
Modal.Action.DATA in the modal and dispatch a
Modal.Action.DATA action from your app.