• Plain JavaScript
  • React

Modal

Note

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.

A close-up image of a modal. In the modal's title area is the word title. In the upper-right corner is an x icon to dismiss the modal. In the body of the modal, the word message appears. The modal features two buttons: a white button with the label Secondary action, and a green button with the label Primary action.

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:

  1. Plain JavaScript
  2. React component

Plain JavaScript

Anchor link to section titled "Plain JavaScript"

Example code

Anchor link to section titled "Example 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.

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

Create a message modal

Anchor link to section titled "Create a message modal"

Create a message modal using the message option. Message modals support plain text content of any length.

Create an iframe modal

Anchor link to section titled "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

Anchor link to section titled "Create an iframe modal with an absolute URL"

Note

The absolute url option allows you to specify a sub domain, but not a different domain from the app url.

Create an iframe modal with a relative path

Anchor link to section titled "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 https://myapp.com/settings.

Open and close a modal

Anchor link to section titled "Open and close a modal"

Open and close the modal by dispatching the OPEN and CLOSE actions.

Add footer buttons

Anchor link to section titled "Add footer buttons"

Add buttons to the modal footer. All modals support one primary button and multiple secondary buttons. To learn more about buttons, refer to Button.

Subscriptions

Anchor link to section titled "Subscriptions"

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

Anchor link to section titled "Unsubscribe from all"

Call unsubscribe to remove all subscriptions on the modal and its children (including buttons).

Unsubscribe from only modal actions

Anchor link to section titled "Unsubscribe 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.

Update options

Anchor link to section titled "Update 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 footer buttons

Anchor link to section titled "Update footer buttons"

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

Anchor link to section titled "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.

The 3 values for Modal.Size are Small, Medium and Large.

Note

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.

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

Set modal size automatically

Anchor link to section titled "Set 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, be aware that it applies height: 100% to the <body> element by default. You will need to override this style on your modal page.

Note

The automatic modal sizing utility works with all size options.

Communicate with the parent page

Anchor link to section titled "Communicate with the parent page"

Note

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.

Note

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.

React

Anchor link to section titled "React"

Example code

Anchor link to section titled "Example code"

Import the Modal component from @shopify/app-bridge-react.

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

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

Props

Anchor link to section titled "Props"
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

Note

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.

ActionProps

Anchor link to section titled "ActionProps"
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

On this page

  • Plain JavaScript
  • React