Toast

Toasts contain updates or messages about the status of an application’s process.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-react

Anatomy

Image of a Toast Popup.

  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.

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.
TypeEmphasisPurpose
ToastsLowAlthough Toasts communicate low priority information, user action is still required to dismiss Toasts.
BannersMediumBanners should be used for messages about errors and alerts. They do not disappear unless the user resolves the required action.
DialogsHighDialogs are reserved for messages of the highest priority. They command user action.

Examples

Basic Usage

Below are examples we expect will work for most use cases. Note that all examples include icons as they are an important signifier to communicate meaning. For this reason, Toast notifications should always include an icon.

Complete Example with Popper

We use Popper to position Toast. Here's an example of how to use them together.

Success

Your workbook was successfully processed.

Error

WithCloseButton

With RTL

Props

NameTypeDefaultDescription
iconCanvasSystemIcon | undefinedcheckIconThe icon of the Toast.
iconColorstring | undefinedcolors.greenApple400The color of the Toast icon.
children*stringThe text of the Toast message.
onClose(() => void) | undefinedThe function called when the Toast is closed.
onActionClick(() => void) | undefinedThe function called when the Toast action is clicked.
actionTextstring | undefinedThe text of the Toast action.
model{ state: { stackRef: RefObject<HTMLDivElement>; targetRef: RefObject<HTMLButtonElement>; initialFocusRef: RefObject<any> | undefined; returnFocusRef: RefObject<...> | undefined; placement: Placement; id: string; visibility: Visibility; }; events: { ...; }; } | undefinedOptional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
elemPropsHook(<TProps>(model: { state: { stackRef: RefObject<HTMLDivElement>; targetRef: RefObject<HTMLButtonElement>; initialFocusRef: RefObject<any> | undefined; returnFocusRef: RefObject<...> | undefined; placement: Placement; id: string; visibility: Visibility; }; events: { ...; }; }, elemProps: TProps) => any) | undefinedOptional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

Accessibility Guidelines

  • When a Toast is displayed, make sure this is announced to users using a screen reader.
  • A Toast must persist visually until a user interacts with it.
  • Toasts should be consistently placed so users can reliably navigate to them.
  • Avoid displaying a Toast on page load.

Content Guidelines

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for.

FAQ Section