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.


  title="Upgrade your Shopify POS with the Retail Package"
    content: 'Add Retail Package',
    onAction: () => this.setState({open: false}),
    content: 'Cancel',
    onAction: () => this.setState({open: false}),
  onClose={() => this.setState({open: false})}
Controls the height of the modal (in pixels)
Whether the modal is open or not
Primary action for the modal
Collection of secondary action for the modal
The URL that will be loaded as the content of the modal
The content for the title of the modal
Controls the width of the modal (in pixels)
() => void
Callback when the modal is closed

Screenshot examples

This static image is provided to help visualize the interface since embedded components can only be rendered inside the Shopify admin.


Screenshot modal component


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


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


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


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