This page was printed on Nov 18, 2019. For the current version, visit https://help.shopify.com/en/api/embedded-apps/app-bridge/actions/modal.
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.
The Modal action set allows you to open two types of modal: message and iframe.
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 an iframe modal with an absolute url
Create an iframe modal a relative path
The iframe URL will be set to a path that's relative to your app root:
Create a modal with footer buttons
You can attach buttons to the modal footer. To learn more about buttons, see Button.
Subscribe to actions
You can subscribe to modal actions by calling subscribe. This returns a function that you can call to unsubscribe from the action:
You can call unsubscribe to remove all subscriptions on the modal and its children (including buttons):
Unsubscribe from modal actions only
You can call unsubscribe with 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 children 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 Modal.Size value:
There are four values for Modal.Size: Small, Medium, Large, Auto.
Set modal size automatically
Iframe modals can automatically expand to fit their contents, using the Auto size:
Automatic modal sizing requires the style overflow: hidden on the <body> element of your modal page. Otherwise, you’ll see double scrollbars.
Avoid setting height, margin or 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.