Embedded modal

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

This component only works within embedded apps. Read the Embedded App SDK (EASDK) getting started guide for more details on how to use the EASDK with Polaris.


Examples

<Modal
  src="https://my-app.com/update-information"
  open={this.state.open}
  title="Edit account information"
  primaryAction={{
    content: 'Update account',
    onAction: () => this.setState({open: false}),
  }}
  secondaryActions={[{
    content: 'Change account',
    onAction: () => this.setState({open: false}),
  }]}
  onClose={() => this.setState({open: false})}
/>
Name
Type
Description
open*
boolean
Whether the modal is open or not
src*
string
The URL that will be loaded as the content of the modal
title
string
Modal title, in large type
width
enum
Controls the width of the modal
height
number
The height of the modal (in pixels)
primaryAction
Action
Primary action
secondaryActions
Action[]
Collection of secondary actions
onClose*
function()
Callback when the modal is closed

Purpose

Think about the merchant problem this component solves when you’re using it:

Problem

Merchants need a way to focus on certain tasks that can’t be left half-finished.

Solution

Embedded modals require merchants to take an action before they can continue working in other parts of Shopify. It helps them maintain focus or stay in the workflow because the changes can’t be automatically saved.


Best practices

Embedded modals should:

  • Be used for in-context tasks that require an explicit action to be taken
  • Be used for focused, specific tasks that can’t be left half-completed
  • Include no more than a single primary call to action
  • Not be used as a way to present additional sections of content without actions because they can disrupt a merchant’s workflow
  • Not be used for complicated flows that require a merchant to take multiple paths or complete more than one primary task

Content guidelines

Title

Titles should be:

  • Informative and descriptive
    • They should label the type of content grouped in the modal
  • 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

  • Edit the email address for this order

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.

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

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