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.



The content to display inside modal (Modal use only)
Inner content of the footer (Modal use only)
Controls the height of the modal (EASDK use only, in pixels)
The name of the modal content iframe
Disable animations and open modal instantly (Modal use only)
Increases the modal width (Modal use only)
Limits modal height on large sceens with scrolling (Modal use only)
Replaces modal content with a spinner while a background action is being performed (Modal use only)
Whether the modal is open or not
EASDKAction | ComplexAction
Primary action
EASDKAction[] | ComplexAction[]
Collection of secondary actions
Automatically adds sections to modal (Modal use only)
The url that will be loaded as the content of the modal
string | React.ReactNode
The content for the title of the modal (EASDK accepts string)
"large" | "fullwidth"
Controls the width of the modal (EASDK use only)
() => void
Callback when the modal is closed
(evt: SyntheticEvent) => void
Callback when iframe has loaded (Modal use only)
() => void
Callback when modal transition animation has ended (Modal use only)

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

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 merchants’ workflows
  • Not be used for complicated flows that require merchants 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 merchants 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 merchants 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