Modal

Modals are overlays that prevent merchants from interacting with the rest of the application until a specific action is taken. They can be disruptive because they require merchants to take an action before they can continue interacting with the rest of Shopify. It should be used thoughtfully and sparingly.

Examples

Use as the default option for a modal.

Drag to resize example

Props

children
React.ReactNode
The content to display inside modal (stand-alone app use only)
iFrameName
string
The name of the modal content iframe
instant
boolean
Disable animations and open modal instantly (stand-alone app use only)
large
boolean
Increases the modal width (stand-alone app use only)
limitHeight
boolean
Limits modal height on large sceens with scrolling (stand-alone app use only)
loading
boolean
Replaces modal content with a spinner while a background action is being performed (stand-alone app use only)
messageEmbedded app only
string
Message to display inside modal
openRequired
boolean
Whether the modal is open or not
primaryAction
AppBridgeAction | ComplexAction
Primary action
secondaryActions
AppBridgeAction[] | ComplexAction[]
Collection of secondary actions
sectioned
boolean
Automatically adds sections to modal (stand-alone app use only)
sizeEmbedded app only
"Small" | "Medium" | "Large" | "Full"
Controls the size of the modal
src
string
The url that will be loaded as the content of the modal
title
string | React.ReactNode
The content for the title of the modal (embedded app use accepts string only)
onCloseRequired
() => void
Callback when the modal is closed
onIFrameLoad
(evt: SyntheticEvent) => void
Callback when iframe has loaded (stand-alone app use only)
onScrolledToBottom
() => void
Callback when the bottom of the modal content is reached
onTransitionEnd
() => void
Callback when modal transition animation has ended (stand-alone app use only)

Accessibility

  • Modals use ARIA role=”dialog” to convey to screen reader users that they work like native dialog windows.
  • If you set the title prop to give the modal component a heading, then the title is used to label the dialog element with aria-labelledby. This helps to convey the purpose of the modal to screen reader users when it displays.

Keyboard support

  • When a modal opens, focus moves automatically to the modal container so it can be accessed by keyboard users
  • While the modal is open, keyboard focus shouldn’t leave the modal
  • Merchants can dismiss the modal with the keyboard by activating the X button, the Cancel button if one is provided, or by pressing the Esc key
  • After a modal is closed, focus returns to the button that launched it

Modal with primary action

Use to let merchants take a key action.

Modal with primary action on Android

Modal with primary and secondary actions

Use to let merchants take key actions at the bottom of the modal.

Modal with primary and secondary actions on Android

Warning modal

Use to make it clear to the merchant that the action is potentially dangerous. Only use this option when the merchant is about to perform an action that can’t be undone or is difficult to undo.

Warning modal on Android

Accessibility

See Material Design and development documentation about accessibility for Android:

Modal with primary action

Use to let merchants take a key action.

Modal with primary action on iOS

Modal with primary and secondary actions

Use to let merchants take key actions at the bottom of the modal.

Modal with primary and secondary actions on iOS

Warning modal

Use to make it clear to the merchant that the action is potentially dangerous. Only use this option when the merchant is about to perform an action that can’t be undone or is difficult to undo.

Warning modal on iOS

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Use in an embedded application (deprecated)

Passing an API key to the app provider component causes the modal component to delegate to the Shopify App Bridge instead of rendering as it would in a stand-alone application.

In an embedded application context, not all documented properties are available. Some properties are only available in stand-alone applications.

Properties that are available only in a stand-alone context are documented as (stand-alone app use only). For instance the children property is documented as (stand-alone app use only).

The following example shows the modal component in an embedded application context:

function EmbeddedAppModalExample() {
  const [modalOpen, setModalOpen] = useState(false);

  const handleModalClose = useCallback(() => setModalOpen(false), []);

  return (
    <AppProvider apiKey="YOUR_API_KEY" i18n={{}} shopOrigin="YOUR_SHOP_ORIGIN">
      <Modal
        src="https://my-app.com/upgrade-to-retail-package"
        open={modalOpen}
        title="Upgrade your Shopify POS with the Retail Package"
        primaryAction={{
          content: 'Add Retail Package',
          onAction: handleModalClose,
        }}
        secondaryActions={[
          {
            content: 'Cancel',
            onAction: handleModalClose,
          },
        ]}
        onClose={handleModalClose}
      />
    </AppProvider>
  );
}

Deprecation rationale

As of v3.17.0, using Modal in an embedded app is deprecated. Support for this will be removed in v5.0 as the underlying Shopify App Bridge library will be removed from Polaris React. Learn more about the deprecation rationale. Use Modal from @shopify/app-bridge-react instead.


Best practices

Use modals when merchants must complete an action before they can continue with the main workflow. Avoid using modals to display complex forms or large amounts of information.

Modals should:

  • Require that merchants take an action.
  • Close when merchants press the X button, the Cancel button, or the Esc key, not when merchants click or tap the area outside the modal.
  • Not have more than two buttons (primary and secondary) at the bottom. This prevents unclear action hierarchy and crowding on mobile screens. Since modals are for focused tasks, they should have focused actions. In some cases however, a tertiary action may be appropriate.

Content guidelines

Title

Modal titles should:

  • Edit email address

  • Delete customer?

  • Discard unsaved changes?

  • Edit the email address for this order

  • Are you sure you want to delete customer?

  • Discard?

Body content

Body content should be:

  • Actionable: start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don’t use permissive language like "you can".
  • Notification emails will be sent to this address.

  • This can’t be undone.

  • You can edit the email address where emails will be sent.

  • Are you sure you want to delete the variant Dark Blue Tee/Small/Silk? You cannot reverse this.

  • Structured for merchant success: always put the most critical information first.
  • Clear: use the verb “need” to help merchants understand when they’re required to do something.
  • To buy a shipping label, you need to enter the total weight of your shipment, including packaging.

  • To buy a shipping label, you must enter the total weight of your shipment, including packaging.

Primary and secondary actions

Actions should be:

  • Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive a merchant by mislabeling an action.
  • Create order

  • Buy shipping label

  • New order

  • Buy

  • Action-led: actions should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on actions except in the case of common actions like Save, Close, Cancel, or OK.
  • Activate Apple Pay

  • View shipping settings

  • Try Apple Pay

  • View your settings

  • Scannable: avoid unnecessary words and articles such as the, an, or a.
  • Add menu item

  • Add a menu item

Tertiary actions

Tertiary actions should:

  • Only be used when the action requires the context of the content in the modal
  • Never be used to dismiss the modal
  • Use a plain button for a tertiary action if needed Screenshot of modal with a plain button as a tertiary action

  • Use a tertiary action for a destructive action Screenshot of modal with a destructive button as a tertiary action

Footer

Body content should be:

  • Actionable: start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don’t use permissive language like "you can".
  • Notification emails will be sent to this address.

  • You can edit the email address where emails will be sent.

  • Structured for merchant success: always put the most critical information first.
  • Clear: use the verb “need” to help merchants understand when they’re required to do something.
  • To buy a shipping label, you need to enter the total weight of your shipment, including packaging.

  • To buy a shipping label, you must enter the total weight of your shipment, including packaging.