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)
footer
React.ReactNode
Inner content of the footer (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)

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

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

Use in an embedded application

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:

class EmbeddedAppModalExample extends React.Component {
  state = {
    modalOpen: false,
  };

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

Best practices

Modals should:

  • Only be closed by clicking the X or Cancel button and not by clicking the backdrop outside the modal, which is a large touch target that could result in accidental presses. Modals require merchants to take an action and should prevent the merchant from accidentally closing the modal without completing the required task.
  • Avoid having 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

Titles should be:

  • Informative and descriptive
    • They should label the type of content grouped in the modal
    • Use a clear {verb}+{noun} question
  • Concise and scannable:
    • Use simple, clear language that can be read at a glance
    • Keep headings to single sentence and avoid using punctuation such as periods, commas, or semicolons
    • Avoid articles (the, a, an) in microcopy headings to keep content short and actionable
    • Written in sentence case (first word capitalized, the rest is lowercase)
  • 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.