Toast

Guidelines#

About Toast#

Use a toast to communicate a direct response to a user based on their action. Using a toast lets users know that their action was acknowledged.

Toasts appear over content on a page and stack vertically. All toasts have a close button so that users can dismiss any toasts that may be blocking underlying page content.

Use a toast for one of these types of responses:

• Success. Confirm a successful or completed action.
• Warning. Help a user avoid a future issue that might happen based on their action. If the user can take an immediate action to avoid the issue, provide a way to do that. In most cases, a warning toast lets users know that their current action was successful but may have triggered a related issue, or that their action can't be completed because of an issue that they need to fix outside their current flow.
• Error. Communicate an issue that's preventing a user from completing their current action and can be fixed within their current flow.
• Neutral or general response. Let a user know that an asynchronous process has been triggered based on their action, especially if they have to wait for the process to finish before continuing a workflow. This could include a large download or a request that's been sent to a third party.

In general, use Toasts for response to user action. To decide whether you should use Toasts or another type of messaging, jump to Toasts vs. Alerts vs. Inline messaging.

Accessibility#

If you make a toast automatically time out, consider users that have different reading speeds, vision levels, and literacy levels (more details in the research insight below).

We recommend giving users about 500 milliseconds per word. For short toasts (about 5–10 words), give users about 2,000–4,000 milliseconds to read the toast message. For toasts at our max suggested length of 140 characters, that's about 30,000 milliseconds for about 55 English words. In this case, consider not making the toast automatically time out since the longer content length could suggest that there's information worth persisting for the customer.

In addition to reading time, consider the time users need to make a decision based on the message. If a toast has any interactive element in it, like a link or button, don't add an automatic time-out to the toast.

Don't use toasts to communicate dynamically changing content, including progress bars. Since toasts have ARIA role=status, they'll need to trigger a status update to assistive technology, such as screen readers, each time the content changes, which could get annoying. Use a non-modal dialog, modal, or show the changing content on the underlying page instead.

Examples#

Here are ways that you can compose neutral, warning, error, success, and dismissible toasts.

Showing, dismissing, and timing out a toast#

The Toaster is a convenient way to manage showing and dismissing Toasts. The Toaster comes in two parts:

• A useToaster hook that handles adding, removing, auto dismissing and state.
• A <Toaster /> component that handles rendering toasts into the DOM.

useToaster hook#

The easiest way to use the Toaster is to use the useToaster hook. It will handle adding and removing a Toast and can be used to set automatic time-outs. The useToaster hook will then return the props needed to render the Toasts within the Toaster component.

useToaster returns 3 things:

• An array of toasts to be rendered in the DOM.
• A push method used to add a Toast to the Toaster.
• A pop method used to remove a Toast from the Toaster via its ID.

Below is a form you can use to create toasts dynamically using the Toaster. The form data is used to push a new Toast to the Toaster.

Adding a Toast#

You can push a Toast to the Toaster stack based on any action or event. In this example it's based on a button click:

const MyComponent = () => {
  const toaster = useToaster();
  const handleClick = () => {
    toaster.push({
      message: 'Selection was successfully saved to your profile',
      variant: 'success',
    })
  }
  return(
    <>
      <Button variant="primary" onClick={handleClick}>
        Add a toast
      </Button>
      <Toaster {...toaster} />
    </>
  )
}

Removing a Toast#

You can optionally provide an id to a toast when you push it to the stack. The ID can then be used to programmatically pop the Toast from the stack:

toaster.push({
  message: 'Selection was successfully saved to your profile',
  variant: 'success',
  id: 'custom_id',
})
toaster.pop('custom_id')

When providing your own custom ID, make sure they are unique.

Automatic dismissal#

You can optionally provide a time-out to a toast, after which the Toast is automatically dismissed. This can be done by setting a dismissAfter value. The value must be a valid time-out, set in milliseconds.

toaster.push({
  message: 'Selection was successfully saved to your profile',
  variant: 'success',
  id: 'custom_id',
  dismissAfter: 4000
})

Add an automatic time-out if all these conditions are true:

• The user wouldn't need to remember or copy the information in order to continue with their current flow, or any future flow.
• The toast doesn't have any interactive content, such as a link or button.

We recommend giving users about 500 milliseconds per word before timing out a toast.

Toaster component#

The <Toaster /> component handles rendering the toasts it is passed via props. It handles how the Toast enters and leaves the UI.

If you pass it the returned state of the useToaster hook, state, pushing, popping, and handling browser window time-outs is taken care of for you.

const toaster = useToaster();
return <Toaster {...toaster} />;

Neutral Toast#

Let a user know that a background process has been triggered based on their action, especially if they have to wait for the process to finish before continuing a flow.

<Toast onDismiss={() => alert('dismissed')} variant="neutral">
  <Text as="span">
    Your function is currently being deployed.
  </Text>
</Toast>

Success Toast#

Use a success toast to confirm a successful or completed action. If a creation flow is a 2-step process—a user creates an object, then edits the details of that object—confirm the completion after each step with a toast.

Provide an "undo" action in the toast if it's easily and safely reversible, and you're able to take the user back to their previous state. For example, you can allow the user to undo an action through a toast if:

• They submitted a short form that updates something. Undoing the action can take them back to their filled form with any sensitive fields cleared.

• They deleted non-sensitive information we'd want them to easily retrieve.

<Toast onDismiss={() => alert('dismissed')} variant="success">
  <Text as="span">
    Your email address has been updated. You can view your profile <Anchor href="#">here</Anchor>.
  </Text>
</Toast>

Warning Toast#

Use a warning toast to help a user avoid a potential future issue that might happen based on their action. If the user can take an immediate action to avoid the issue, provide a way to do that. In most cases, a warning toast lets users know that their current action completed but may have triggered a related issue, or that their action can't be completed because of an issue that they need to fix outside their current flow.

Be cautious when using a warning toast because they can be stressful for a user to see. If the information you're trying to convey is not very critical, consider using a neutral toast instead.

<Toast onDismiss={() => alert('dismissed')} variant="warning">
  <Text as="span">
    The phone number has been deleted. Functions still using this phone number may fail. Verify there are no functions tied to that number <Anchor href="#">here</Anchor>.
  </Text>
</Toast>

Error Toast#

Use an error toast to help a user understand an issue that's preventing them from completing their current action. Provide a way to resolve the issue either in the underlying page content or in the toast.

Be cautious when using an error alert because they can be stressful for a user to see.

<Toast onDismiss={() => alert('dismissed')} variant="error">
  <Text as="span">
    There was an error when deleting the profile. Please try again.
  </Text>
</Toast>

Composition Notes#

Keep toast text brief and scannable by placing only the highest priority information in it. Too much text in a toast can overwhelm a user. Aim for no more than 140 characters in a toast, and keep the text directly related to the user's current action. Success toasts generally run about 50 characters long, while all other alerts might run about 100 characters long. However, don't sacrifice being direct and straightforward for a shorter message.

Be specific in your response to the user's action and if applicable, provide a resolution by navigating a user to another page using an anchor. Be cautious about using a button in a toast since it should be used only to trigger an action. If you must use a button, use a small secondary button in a toast.

When to use a Toast#

Help users avoid scenarios where more than 3 toasts could show at a time. If more than 3 could appear at a time, show only one toast that summarizes the information you were intending to show in all of the toasts.

Toast vs. Alerts vs. Inline messaging#

To communicate feedback on a user action, use a toast or in-page validation (e.g., full-page confirmation, inline error). You may also want to pair a toast with in-page validation. For example, when a user submits a long form, you can show an error toast that lets users know they need to fix some form fields, while also showing inline errors on each incorrect field.

To communicate information from the system that isn't triggered by a user action, use an alert or other in-page messaging.

Use Toasts when...#

• You need to communicate a direct response to a user action. Example: "asset.jpg" successfully added.
• You're providing only one link or button to help a user continue a flow.

Use Alerts when...#

• You need to notify a user about a high-priority or time-sensitive change that isn't triggered by a user action.
• You're providing only one link or button to help a user resolve an issue.

Use in-page messaging, e.g., inline errors, in-page call-outs when...#

• You need to communicate a direct and contextual response to a user action.
• You need to provide links or buttons next to an in-page element.
• You need to communicate dynamically changing content, like a progress bar. Use a non-modal dialog instead.
• You need to communicate general promotional information to a user that is unrelated to completing their current action.

Use an alert dialog or modal when...#

• You need to interrupt a user flow.
• You need to provide multiple links or buttons to help a user continue a flow.

Anatomy#

Usage Guide#

API#

Installation#

yarn add @twilio-paste/toast - or - yarn add @twilio-paste/core

Usage#

import {Toast, Toaster} from '@twilio-paste/toast';
const Component = () => {
  const toaster = useToaster();
  return <Toaster {...toaster} />;
};

Toaster component#

If you choose to handle state entirely yourself, you can use <Toaster /> on its own, but you are fully responsible for handling state, time-outs, and the dismiss functionality.

<Toaster
  toasts={[{
    id: '',
    message: '',
    variant: ''
    dismissAfter: ''
  }]}
  pop={(id) =>{
    // called when a toast is dismissed
  }}
/>

Toast Props#

useToaster return state#

UseToasterToast#

Toaster Props#

ToasterToast#

ToastContainer Props#