Toast

Anatomy

1. Container: Rectangular container that houses the icon and text for toasts.
2. Icon: An Icon is optional and indicates the status of the message being displayed.
3. Text: Description text for explaning what's going on with a process that just occurred.
4. Action Link: Optional link for directing users to find helpful information regarding the action they just took.
5. Close Button: Close Button is optional and are provided when a Toast doesn't have a timer to close itself.

Usage Guidance

• Toasts should communicate information about the status of an application’s process, like confirmation that a task has been successfully submitted.
• They are low-emphasis and meant to be temporary, but can also be dismissed manually with a Close Button.
• Toasts should overlap and visually look like they are in front of other UI elements without blocking important actions.
• Action Links should be short. Including a non-required action, such as “View More,” is optional.
• For more information on Toast placement, please reference the Notification Pattern Guidance. For help deciding if a Toast is the best component for your use case, reference this decision tree.

When to Use

• Use Toasts when communicating updates about the process of an application.
• Use Toasts for lower priority messages that do not require user action.

When to Use Something Else

• Consider using Banners if communicating messages about system errors or alerts.
• Consider using Dialogs when informing users about critical information that requires user action or decision.

Examples

Basic Example

Toast includes a container Toast component and the following subcomponents: Toast.Body, Toast.CloseIcon, Toast.Icon, Toast.Message, and Toast.Link.

Toast supports different modes through the mode prop: status, alert, and dialog. Each mode conveys a different purpose of the message and assigns the necessary ARIA attributes to support that purpose and provide an accessible experience.

By default, mode is set to status, which indicates the message contains advisory information such as a successful action.

A status Toast will wrap the message within a polite ARIA live region with a role of status.

Here's a more complete example with a button which triggers a dismissable Toast. The Toast is positioned using Popper.

Alert

Set the mode prop to alert to convey urgent and important information such as an error.

An alert Toast will wrap the message within an assertive ARIA live region with a role of alert.

Dialog

Set the mode prop to dialog to convey the presence of a follow-up action. If you use this mode, you need to add an aria-label. This aria-label should be additional information for the Toast such as notification. The Toast will also add an aria-describedby that links the Toast to Toast.Message so that it is read out to screen readers. The aria-label should be different that the contents of the Toast so there is no duplication being read out by screen readers.

Screen readers will read the Toast out in the following order: "Notification: Your workbook was successfully processed."

Note: You must use the Toast.Message subcomponent when the mode is dialog so that id is tied to the message for accessibility. You can also pass in a model with useToastModel to provide a specific id for the Toast.Message

export const CustomIDToast = () => {
  const model = useToastModel({
    id: '12df5',
    mode: 'dialog',
  });
  return (
    <Toast model={model}>
      <Toast.Icon icon={checkIcon} color={colors.greenApple400} />
      <Toast.Body>
        <Toast.Message>Your workbook was successfully processed.</Toast.Message>
        <Toast.Link href="#href">View More Details</Toast.Link>
      </Toast.Body>
    </Toast>
  );
};

Toast.CloseIcon may be included within a dialog Toast to create a Toast with both an action link and a close button.

Right-to-Left (RTL)

Toast supports right-to-left languages when specified in the CanvasProvider theme.

Component API

import { Toast } from "@workday/canvas-kit-react/toast";

const MyToast = (props: CardProps) => (
   <Toast mode="dialog" aria-label="notifcation">
     <Toast.Icon icon={checkIcon} color={colors.greenApple400} />
     <Toast.Body>
       <Toast.Message>Your workbook was successfully processed.</Toast.Message>
       <Toast.Link href="#hreflink">Custom Link</Toast.Link>
     </Toast.Body>
     <Toast.CloseIcon aria-label="Close" onClick={handleClose} />
   </Toast>
);

<Toast.Body>
 <Toast.Message>Your workbook was successfully processed.</Toast.Message>
 <Toast.Link href="#hreflink">Custom Link</Toast.Link>
</Toast.Body>

<Text variant="error" typeLevel="subtext.large">Error text</Text>

Accessibility Guidelines

How Toasts Impact the Accessible Experience

Toasts can be easy for users to miss and they will not be the most robust way to send users information. Toasts might dynamically appear and disappear outside of a low vision user’s magnified view. Screen readers must announce passive toasts as they appear on screen in real-time, and users must be able to navigate to an actionable toast without relying on a mouse pointer.

Alert notifications should be reserved for time-sensitive and urgent information. Alerts are disruptive, and are intended to interrupt screen reader speech output. Status notifications are recommended for most cases because they will “politely” wait for users to finish what they are doing.

Refer to Accessibility Considerations in Notification Patterns for more information.

Keyboard Interaction

Interactive elements in a Toast must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

User-generated actionable Toasts must move keyboard focus to the first interactive element inside the Toast.

Toast must support the following keyboard interactions:

• Tab: focus the close button or action link in the Toast
• Enter or Space: activate the close button or action link in the Toast

Screen Reader Interaction

Toast must communicate the following to users:

• Text content of the Toast when it appears in real-time

Design Annotations Needed

• Define notification type “status” or “alert”

Implementation Markup Needed

• ARIA live regions work by dynamically inserting content updates inside of an element with the aria-live attribute set. For more information, refer to Screen Reader Notifications
• When an Actionable Toast is generated from a user action, set keyboard focus to the first interactive element in the toast.
• When a toast is generated by the system, avoid moving the keyboard focus away from users’ context. Use an ARIA live region instead.
• [Included in component] For time-sensitive notifications, set aria-live=”assertive” and role=”alert” to interrupt screen reader users. Otherwise, set aria-live=“polite” and role=”status” when the notification is not urgent.

Content Guidelines

• When writing Toasts, refer to the Tooltips and Toasts section of the Content Style Guide.