Using modals in your app

You may have reached this guide after seeing that the Polaris Modal has been deprecated. There are a few key reasons that we recommend using App Bridge modals instead of Polaris Modals.

Modals are used across the Shopify admin. They are centered in the page with a background overlay obscuring the sidebar and top bar.

When you use a Polaris modal inside of your app, it's rendered directly in the app and centered in the app frame, since the app frame deos not span the whole space of the Shopify admin. The app frame behind the modal is greyed out but the side bar and top bar of the Shopify admin remain unchanged:

When you use an App Bridge modal inside of your app, it's rendered outside of the app frame in the Shopify admin and centered in the page. The entire Shopify admin, including the sidebar and top bar, are greyed out:

Another aspect of visual consistency is the modal header and footer. In order to maintain that consistency, we control the rendering of the modal header and footer inside the Shopify admin and put constraints around the components rendered inside of it.

Polaris is versioned. Its code is bundled into your app code. If you don't keep up to date with the latest versions, then the styling can quickly become out of sync with the rest of the Shopify admin. The code for App Bridge modals is loaded from a CDN and Shopify regularily updates it. As such, you don't need to worry about dependency updates because Shopify will keep App Bridge modals up to date with the rest of the Shopify admin.

App Bridge modals are different than other modals you may have used, such as the now-deprecated Polaris Modal.

To center the modal in the Shopify admin and control the layout of the modal header and footer, modals are rendered by the Shopify admin rather than directly in your app. To center a modal, we render a modal and create an iframe inside of it that is same-origin to your app. This iframe is then used to either load the custom HTML content you provide or the src URL for a route in your app.

Modals can be created with simple HTML elements as content.

For more information on usage, refer to the ui-modal component. When you open a modal with HTML content, App Bridge moves this content into the modal's iframe. It also copies the stylesheets from your app into the modal frame to ensure your modal styles match your app styles.

These modals are meant to be used for simple use cases. Go to the Examples section to see some common use cases and the Limitations section to learn about what can't be done using these modals.

You can only provide a single parent element, commonly a p, form, or a div. This is because App Bridge needs a single DOM element to search for when moving the content into the modal frame.

We provide the @shopify/app-bridge-react library that contains React wrappers for App Bridge components, such as the Modal React component. Using this component has an added benefit that you are not limited to a single parent element like you are when using standard HTML content. This package is versioned for API updates but will still receives automatic updates to things like modal styling as it relies on the App Bridge script from the Shopify CDN.

If you don't use the Shopify App Bridge React package, then you'll need to set up a React portal for the React components inside of your modal as they're rendered in a different part of the DOM. We recommend you use the Modal React component to avoid this complexity, as it sets this up for you.

You can use a modal with custom content to achieve any of the following examples:

• Simple message modal
• Simple form

You might use an HTML content modal to show a confirmation dialog for a destructive action. You can provide a simple message string in a p element and buttons to control deleting and cancelling.

You might use an HTML content modal to present a simple form to the merchant. You can provide the form inputs inside of a form element and use the data-save-bar attribute to connect with the contextual save bar in the Shopify admin.

App Bridge is moving the HTML content you provide in the ui-modal element into the iframe created in the modal in the Shopify admin.

If you require any of the functionality listed in these limitations, then we recommend using the src modal explained in the Modals with a route section.

App Bridge only copies the HTML elements and stylesheets into the modal frame. Custom JavaScript and template tags that you rely on in your app are not copied.

As the modal is rendered in a different frame, you do not have direct access to the document. Some npm libraries are incompatible with this approach, such as commonly used drag-and-drop libraries.

Using React portals for custom React component content is a requirement. However, this limits which components can be used inside of the modal. Any nested components built with React Portals are incompatible. If you're using Polaris, commonly used components in this category are the Popover, Tooltip, and Combobox components.

Modals can be created with a src attribute that accepts a same-origin URL to load in the modal frame.

When you open a modal with the src attribute, App Bridge uses this URL as the iframe's src attribute. You will need to setup a route in your app to be used within the modal. Modals rendering a route via the src attribute are the recommend path for rendering complex content or functionality requiring 3rd-party libraries.

One complexity that come with loading a modal iframe within an app iframe is communication between the two frames. You can use the postMessage API to communicate with the parent page from within your modal. You can access postMessage through the window.opener object in the modal and through the modal.contentWindow object in the parent page.

Modals are meant to be used as presentation layers for specific use cases. As such, the available features inside of the modal frame are limited. You're not able to access App Bridge features such as toast directly in your modal. Instead, you should communicate with your main app frame to share state and use App Bridge features.

You're only able to access the environment feature directly from within your modal.

This section provides answers to some commonly asked questions about App Bridge modals.

The App Bridge React Modal component creates a React portal for you so that you can use React components in your simple HTML content modal. This limits which components can be used inside of the modal, as any nested components built with React Portals are incompatible. It is recommend to use the src modal instead when your use case requires these components.

You can use the window.opener property to get a reference to the main app frame window. This can be helpful when communicating state between the frames, be it through postMessage or another method.

No, App Bridge modals work the same in mobile and desktop views.

3rd-party libraries, such as drag-and-drop libraries, may be accessing the document or be otherwise incompatible with custom content modals. You should set up a route in your app for the modal content and use the src modal for use cases like this.

Yes, you need to reinclude any CSS and JS that you need on this page, since it's a separate page loaded in a separate iframe from your main app.