Skip to content Shopify logoPolaris

Toast

The toast component is a non-disruptive message that appears at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action.

Use to convey general confirmation or actions that aren’t critical. For example, you might show a toast message to inform the merchant that their recent action was successful.

import{Toast,Frame,Page,Button}from'@shopify/polaris';import{useState,useCallback}from'react';functionToastExample(){const[active,setActive]=useState(false);consttoggleActive=useCallback(()=>setActive((active)=>!active),[]);consttoastMarkup=active?(<Toastcontent=”消息本身nt"onDismiss={toggleActive}/>):null;return(<div style={{height:'250px'}}><Frame><Pagetitle="Toast example"><ButtononClick={toggleActive}>ShowToast</Button>{toastMarkup}</Page></Frame></div>);}

Props

Want to help make this feature better? Pleaseshare your feedback.

interface ToastProps
content string

The content that should appear in the toast message.
duration? number

The length of time in milliseconds the toast message should persist.

Defaults to5000.
error? boolean

Display an error toast.
onDismiss () =>void

Callback when the dismiss icon is clicked.
action?

Adds an action next to the message.

Required components

The toast component must be wrapped in theframecomponent.

Best practices

Toast should:

  • Be used for short messages to confirm an action
  • Not go over 3 words
  • Rarely be used for error messages

When to use:

  • For success messages
  • Only for non-critical errors that are relevant in the moment and can be explained in 3 words. For example, if there’s an internet connection issue, the toast would say, Internet disconnected.

When not to use:

  • Avoid using toast for error messages. Always try to use a banner to prominently inform merchants about persistent errors.

Content guidelines

Message

Toast messages should be:

  • Short and affirmative
  • 用的模式:名词+动词

Do

  • Product updated
  • Collection added
  • Customer updated
  • Internet disconnected
  • Connection timed out

Don’t

  • No internet connection
  • Can’t charge negative tax rates
  • Your online store has a maximum of 20 themes. Delete unused themes to add more.
  • Your product has been successfully updated
  • We were unable to save the customer
  • Your Order was Archived Today
  • Discount: Saved successfully

Toast with action

Only include an action in toast if the same action is available elsewhere on the page. For example:

  • If merchants need to reload a section, offer the call to action [Reload] in the toast. If they miss the toast message, they can also refresh the entire page.
  • If merchants delete an image, offer the option to [Undo] the deletion. If they miss it in the toast message, they can still retrieve it from somewhere else.

Action should:

  • Keep the action label short, preferably 1 verb.
  • Not have actions, like [Cancel], for dismissing toast. The [X] to dismiss is already included in the component.
  • Be used with a duration of at least 10,000 milliseconds for accessibility.

Do

  • Undo
  • Change
  • Edit
  • View
  • Retry

Don’t

  • OK
  • Got it
  • Cancel product
  • Continue to collection
  • Dismiss

Related components

Accessibility

The content of the toast component is implemented as an ARIA live region usingaria-live="polite". When the toast appears, screen readers should announce the toast text after any other more pressing announcements.

Avoid using toast for critical information that merchants need to act on immediately. Toast might be difficult for merchants with low vision or low dexterity to access because it:

  • Disappears automatically
  • Can’t be easily accessed with the keyboard
  • Might appear outside the proximity of the merchant’s current focus

Toast with action

Make sure that merchants can also accomplish the action in the toast another way, since the toast action may be difficult to access for some merchants. If the toast action is not available somewhere else on the page, for example a retry action that reloads a section, it should have a fallback action, for example a browser refresh.

Toast with action should persist for at least 10,000 milliseconds to give the merchant enough time to act on it.