Alerts

Alerts notify merchants of important system information, and provide feedback on merchant actions.

A button labeled 'Add puzzle' that, once clicked, makes a toast component appear with the text 'Puzzle added'.

Task alerts

Task alerts are initiated in response to merchant actions during a specific task. Task alerts give merchants direct and immediate feedback.

The following are examples of task alerts:

  • A form is successfully submitted.
  • A problem uploading something.
  • The information provided is incorrect or doesn't match the requested format.
An informational banner on top of a page that reads 'USPS has updated their rates' with a link to 'Learn more'.

System alerts

System alerts are initiated by the application or system, independent of merchant actions. System alerts provide updates on background system status or out-of-context events that have finished.

The following are examples of system alerts:

  • Lost network connection.
  • A planned upgrade.
  • The app subscription is expiring soon.

Diagram of the app body within the Shopify admin, and the types of alert patterns: banner (1), inline (2), and toast (3).
  1. Banner (system alert)
  2. Inline (task alert)
  3. Toast (task alert)

The following are common patterns available for merchant alerts:

Pattern Definition Duration and interaction Used to communicate
Banner

Page-level alerts, often system related

or

Contextual alerts that are specific to a card, section, or modal

Banners persist until dismissed by the merchant and can include an action button or link.

Information

Success

Warning

Error

Inline Provides merchants with feedback that's as close to the source as possible Inline alerts persist until the message is resolved by the merchant.

Warning

Error

Toast Short, temporary messages that slide in and out of a page and provide succinct information. Toast alerts without actions can disappear automatically or can be dismissed by the merchant. Success

When you use alerts to communicate important information to merchants, you can choose from a few standard patterns.

Use a default banner when you want to convey general information or actions that aren't critical.

A default banner that reads 'Order archived', styled in gray.

Mandatory

Default banners should be gray and contain only lower priority information that's always dismissible.
Use an informational banner when you need to update merchants about a change or give them advice.
An informational banner that reads 'USPS has updated their rates' with buttons labeled 'Update rates' and 'Learn more', styled in blue.

Mandatory

Make informational banners blue and always make them dismissible.

When you're communicating success, it's important to provide feedback. That means using patterns that inform merchants when a task has been completed successfully.

Toasts inform merchants of a process that the app has performed or will perform. Toasts display temporarily, at the bottom of the interface. Toasts don't require any merchant input to disappear, and they shouldn't interrupt the merchant experience.

A toast placed in the bottom center of the app screen that reads 'Message sent'.

Mandatory

Display toasts in the bottom center of your app screen.
A toast that confirms a 'Message sent' action.

Mandatory

Use toasts for only short messages that confirm an action.
A toast that reads 'Image deleted'.

Required

Make toast messages three words or less.
A toast that reads 'Template duplicated'.

Mandatory

Toasts are only for non-critical messages that are relevant at the moment.
A toast with a generic 'Server error' message.

Caution

Avoid using toasts for error messages. Instead use a banner to prominently inform merchants about persistent errors.
Only use success banners when feedback is delayed, persistent, or has a call-to-action (CTA). Otherwise, use toasts.
A success banner that reads 'Your puzzle report has been created' with a 'View report' button, styled in green.

Mandatory

Make success banners green and include next steps, if applicable.
A success banner with no buttons that reads 'Message sent'.

Unacceptable

Don't use banners to show success messages for actions that merchants have completed. For user-initiated feedback, use success toasts instead.
A success banner with random content and no call-to-action.

Unacceptable

Don't use success banners if there isn't a CTA.

When you're communicating warnings to merchants, you have different options based on what's causing the warning.

Use warning banners to display information that needs attention or that merchants need to take action on.

A warning banner that reads 'Your shipping address needs to be updated' with an 'Edit address' button, styled in yellow.

Mandatory

Make warning banners yellow. Seeing these banners can be stressful for merchants, so use them intentionally.
Denote specific items in a list that you want to make merchants aware of. You can use the Polaris ExceptionList component for this.
A list of customers, where one has a warning that reads 'No address provided' in yellow, with an icon, under the customer's name.

Mandatory

Use inline warnings to draw attention to exceptions in a list, and encourage action when possible.
A list of customers where one has a warning that reads 'No address provided' in yellow, with no icon, under the customer's name.

Unacceptable

Don't use only color to convey a warning. Pair warning messages with a warning icon. This increases accessibility by providing additional identifiers.

When you're communicating problems and errors, use recognizable patterns that inform merchants of the alert's significance. Put error messages as close to the problem as possible.

Error messages are necessary when something isn't working as expected, or when merchants should be alerted to critical disruptions.

When errors happen, they can be frustrating or even scary. Guide merchants to a solution clearly and quickly.

An error banner that reads 'High risk of fraud detected' with a 'View risk analysis' button, styled in red.

Mandatory

Always tell merchants what happened and offer a path forward.
An error banner that reads 'ERR #1337H4X0RZ Your puzzle has caused a complete failure of our interjambs systems'.

Unacceptable

Avoid scary language, technical terms, and jargon.
An error banner that reads 'Oops! We did it again'.

Unacceptable

Avoid humor, idioms, or other words and phrases that might not translate correctly.
Use critical banners when you're communicating problems that need to be resolved immediately for merchants to complete a task.
A critical banner that reads 'You have reached your template limit', styled in red.

Mandatory

Make critical banners red and use them sparingly.
A critical banner that explains the issue and offers a way to contact support.

Mandatory

Provide troubleshooting steps and a clear way to get support.

When you're validating form fields like text fields, place the error message directly below the affected field.

Use red for error message text, because it's a common convention outside of Shopify.

A form field filled with an email address that currently has a typo, making a 'Must be a valid email address' error message appear underneath it.

Mandatory

Place error messages directly below the affected field.
An error message that displays while the cursor is still in the form field

Unacceptable

Don't show an error while merchants are typing, because it can cause confusion. Wait until the keyboard focus moves away from the field, and then show th error.
Denote specific items in a list that you want to make merchants aware of. You can use the Polaris ExceptionList component for this.
A list of customers with one of them having a warning that reads 'Fraudulent charge' in red, with an icon, under the customer's name.

Mandatory

Highlight an exceptional state that encourages clicking on a list item. Lead with what went wrong.
A list of customers with one of them having a warning that reads 'Fraudulent charge' in red, with no icon, under the customer's name.

Unacceptable

Don't use only color to convey an error. Instead, pair the error message with an error icon. This increases accessibility by providing additional identifiers.
If an error applies to a specific card, section, or modal, then place it near the top of the affected element.
A system error that reads 'Service outage', but it appears as an inline error in a list of recent orders.

Unacceptable

Don't nest error messages too deeply within your app's hierarchy. If the error applies more broadly, then place it at the top of the affected element.
A modal with the title 'Username not valid' and a message that reads 'Username must be a valid email address'.

Unacceptable

Don't use toasts and modals to handle error messages. Only place an error message inside a modal if the modal itself is experiencing an error.