Modal
This is a legacy API. Use the latest version of Modal
instead.
Modals are overlays that prevent users from interacting with the rest of the app until they take an action that dismisses the modal.

Modals can be disruptive because they require users to take an action before they can continue interacting with the rest of Shopify. You should use modals sparingly.
The 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.
There are 2 ways to use the modal action:
Anchor to Plain JavaScriptPlain Java Script
Anchor to Example codeExample code
Import the createApp
function from @shopify/app-bridge
and the Modal
from @shopify/app-bridge/actions
. Then use the createApp
function to create an app.
In the following example, config
is a valid App Bridge configuration object. Learn more about configuring App Bridge.
Anchor to Create a message modalCreate a message modal
Create a message modal using the message
option. Message modals support plain text content of any length.
Anchor to Create an iframe modalCreate 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.
Anchor to Create an iframe modal with an absolute URLCreate an iframe modal with an absolute URL
The absolute url option allows you to specify a sub domain, but not a different domain from the app url.
Anchor to Create an iframe modal with a relative pathCreate 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 https://myapp.com/settings
.
Anchor to Open and close a modalOpen and close a modal
Open and close the modal by dispatching the OPEN
and CLOSE
actions.
Add buttons to the modal footer. All modals support one primary button and multiple secondary buttons. To learn more about buttons, refer to Button.
Anchor to SubscriptionsSubscriptions
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.
Anchor to Unsubscribe from allUnsubscribe from all
Call unsubscribe
to remove all subscriptions on the modal and its children (including buttons).
Anchor to Unsubscribe from only modal actionsUnsubscribe from only modal actions
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 you can reuse the buttons in a different modal.
Anchor to Update optionsUpdate options
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 buttons attached to a modal's footer. Any updates made to the modal's footer buttons automatically trigger an UPDATE
action on the modal.
Anchor to Set modal sizeSet 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.
The 3 values for Modal.Size
are Small
, Medium
and Large
.
The full screen modal size has been deprecated in version 1.6.5. If you open a modal with the size set to Full
, then it will display in the default size of Medium
.
The Auto
modal size has been deprecated in version 1.12.x and moved into the setupModalAutoSizing
utility. If you open a modal with the size set to Auto
, then it will default to size Medium
.
Anchor to Set modal size automaticallySet modal size automatically
The 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:
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 React, be aware that it applies height: 100%
to the <body>
element by default. You will need to override this style on your modal page.
The automatic modal sizing utility works with all size options.
Anchor to Communicate with the parent pageCommunicate with the parent page
Available in App Bridge version 1.25.0 and above.
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.
App Bridge serializes data using JSON.stringify
. Objects and arrays can be serialized, but object references (for example, DOM elements) will be lost.
To send data from a modal, dispatch a Modal.Action.DATA
action from your modal:
In your app, subscribe to Modal.Action.DATA
:
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.
Anchor to ReactReact
Anchor to Example codeExample code
Import the Modal
component from @shopify/app-bridge-react
.
In the following example, config
is a valid App Bridge configuration object. Learn more about configuring App Bridge.
When using the App Bridge React library, you need to wrap all of your App Bridge React code inside of a single App Bridge Provider
.
Anchor to PropsProps
Name | Type | Description | Required |
---|---|---|---|
open | boolean | Whether the modal is open or not | Yes |
src | string | The url that will be loaded as the content of the modal | |
title | string | The content for the title of the modal | |
size | "Small" , "Medium" , "Large" | Controls the size of the modal | |
message | string | The message to display inside the modal. If a src prop is specified, this prop will be ignored. | Yes |
primaryAction | ActionProps | Primary action | |
secondaryActions | ActionProps[] | Collection of secondary actions | |
onClose | () => void | Callback when the modal is closed |
The Auto
modal size has been deprecated in version 1.12.x. If you open a modal with the size set to Auto
it will default to size Medium
.
Anchor to ActionPropsAction Props
Name | Type | Description | Required |
---|---|---|---|
content | string | Content the action displays | |
destructive | boolean | Should the action be styled as destructive | |
disabled | boolean | Should the action be disabled | |
external | boolean | Forces url to open in a new tab | |
target | "ADMIN_PATH" , "REMOTE" , "APP" | Where to display the target link | |
url | string | A destination to link to | |
onAction | () => void | Callback when an action takes place |