Embedded alert

Embedded alerts are similar to embedded modals, but use no more than two calls to action and only one string of body text. They are simpler to implement than embedded modals, and add consistency for alert and confirmation messages.

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

Use when you don’t provide onCancel and cancelContent and the merchant must click on the confirmation button to proceed.

<Alert
  title="Accept terms and conditions"
  open={this.state.open}
  confirmContent="I accept"
  onConfirm={() => this.setState({open: false, confirmed: true})}
>
  You must accept the terms and conditions before proceeding.
</Alert>
Name
Type
Description
open*
boolean
Whether the alert is open
children*
string
The content to display inside the alert
title
string
The alert title
destructive
string
For confirming a destructive or dangerous action
confirmContent*
string
The content of the confirmation button
cancelContent
string
The content of the cancel button
onConfirm*
function()
Callback when the confirmation button is clicked
onCancel
function()
Callback when the cancel button is clicked

Purpose

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

Problems

  1. Merchants need a way to be notified about urgent information that requires acknowledgment and doesn’t offer a next step
  2. Merchants need a way to be notified and prevented from immediately completing critical tasks that can’t be undone, or are very difficult to undo

Solutions

  1. Embedded alerts require merchants to acknowledge they’ve seen important information before continuing. In this case, follow the content guidelines for alert messaging.
  2. Embedded alerts can also require merchants to confirm (or back out of) an action before they can continue. It helps them maintain focus and helps prevent them from accidentally making mistakes that are difficult to reverse. In this case, follow the content guidelines for confirmation messaging.

Best practices

Embedded alerts should:

  • Be used for in-context tasks that require information to be acknowledged before continuing, or require confirmation of an action that can’t be undone or is difficult to undo (with the option to back out).
  • For alert messages, keep body content to line of text and don’t use more than one call to action.
  • For confirmation messages, always give merchants the clear option to confirm or back out. Keep body content to one line of text and don’t use more than two calls 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

Embedded alert titles should be:

  • Informative and descriptive:
    • For alert messages, they should label the type of content grouped in the alert
    • For confirmation messages, they should concisely ask if the merchant wants to continue, using a clear {verb}+{noun} question
  • Concise and scannable:
    • Use simple, clear language that can be read at a glance
    • Keep to a single sentence and avoid using any punctuation, with the exception of question marks for confirmation messages
    • Try to avoid articles (the, a, an) to keep content short and actionable
  • Written in sentence case (first word capitalized, the rest is lowercase)

Confirmation messages examples

  • Discard unsaved changes?

  • Delete 2 collections?

  • Delete Dark Blue Tee?

  • Leave page with unsaved changes?

  • Discard?

  • Are you sure you want to delete?

  • Are you sure you want to delete Dark Blue Tee?

  • This page has unsaved changes are you sure you want to leave?

Body content

Body content:

  • For alert messages, clearly explain what the merchant needs to acknowledge
  • For confirmation messages, clearly explain if the action is irreversible or difficult to undo, and use plain language.
  • Be concise: use only one line of text. Don’t start the sentence with, “Are you sure?”.

Confirmation messages examples

  • This can’t be undone.

  • This will delete all edits since you last saved.

  • Leaving this page will delete all unsaved changes.

  • Are you sure you want to delete the variant Dark Blue Tee/Small/Silk? This action cannot be reversed.

  • If you discard changes, you’ll delete any edits you made since you last saved.

  • If you leave this page, all unsaved changes will be lost. Are you sure you want to leave this page?

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.
  • To provide enough context to merchants and to make the copy action-led, we usually use the {verb}+{noun} format in buttons. The exception is with alert and confirmation messaging where common actions are Discard, Cancel, Stay, OK, Got it, or Delete.
  • Scannable: avoid unnecessary words and articles such as the, an, or a.

Confirmation messages examples

Deletions

Before a merchant can delete objects like collections, transfers, products, and variants, we present them with a confirmation message with two calls to action, one to [Cancel] and one to [Delete]. We keep it short and don’t use {verb}+{noun} button copy to make it mobile-friendly.

Primary actions:

  • Delete

  • Remove

  • Erase

  • Discard

Secondary action:

  • Cancel

  • Discard

Discarding changes while on a page

Primary action:

  • Discard

  • Cancel

Secondary action:

  • Keep editing

  • Go back

  • Cancel

Leaving a page with unsaved changes

Primary action:

  • Leave page

  • Exit

  • Delete changes

Secondary action:

  • Stay

  • Go back

  • Cancel

  • Discard

  • Keep editing