Modal

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>
    );
  }
}

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. More information can be found here. Use Modal from @shopify/app-bridge-react instead. For example, import {Modal} from '@shopify/app-bridge-react';.

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.

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)

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

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

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.

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

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

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

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

• 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 present large amounts of additional information or actions that don’t require confirmation, use the collapsible component to expand content in place within the page
• To present a small amount of content or a menu of actions in a non-blocking overlay, use the popover component
• To communicate a change or condition that needs the merchant’s attention within the context of a page, use the banner component