Toast

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

yarn add @workday/canvas-kit-react
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.
  • 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.
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 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.

Your workbook was successfully processed.

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.

Your workbook was successfully processed.

Component API

Toast

Toast is a compound component that has different modes based on its contents. The modes add the proper aria attributes for accessibility

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>
);

Layout Component

Toast supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

Props extend from . If a model is passed, props from ToastModelConfig are ignored.

NameTypeDescriptionDefault
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
childrenReactNode

Children of the Card. Should contain a <Card.Body> and an optional <Card.Heading>

asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

div
refReact.Ref<R = div>

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).

model

Optional 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(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional 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.

Toast.Body

Toast.Body should container Toast.Message and Toast.Link. This ensures proper styling and spacing between elements.

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

Layout Component

Toast.Body supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
modelElementType extends {
  __model: infer M;
} ? M : TModel

Optional 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: TModel,
  elemProps: TProps
) => any

Optional 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.

childrenReact.ReactNode
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

div
refReact.Ref<R = div>

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).

Toast.CloseIcon

Toast.CloseIcon renders a . You can pass an onClick when used with Popper to dismiss the Toast.

Layout Component

Toast.CloseIcon supports all props from thelayout component.

Props

Props extend from button. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
variant'inverse'

Variant has an option for inverse which will inverse the styling

isThemeableboolean
iconPosition 'start' 'end'

Button icon positions can either be start or end. If no value is provided, it defaults to start.

'start'
fill

The fill color of the SystemIcon. This overrides color.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

size

There are four button sizes: extraSmall, small, medium, and large. If no size is provided, it will default to medium.

styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
background

The background color of the SystemIcon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
childrenReactNode
icon

The icon of the Button. Note: not displayed at small size

accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

backgroundHover

The background color of the SystemIcon on hover.

colorHover

The hover color of the SystemIcon. This defines accentHover and fillHover. colorHover may be overriden by accentHover and fillHover.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

colors

Override default colors of a button. The default will depend on the button type

fillIconboolean

Whether the icon should received filled (colored background layer) or regular styles. Corresponds to toggled in ToolbarIconButton

shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic

false
growboolean

True if the component should grow to its container's width. False otherwise.

modelElementType extends {
  __model: infer M;
} ? M : TModel

Optional 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: TModel,
  elemProps: TProps
) => any

Optional 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.

asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

button
refReact.Ref<R = button>

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).

Toast.Icon

ToastIcon renders a SystemIcon where you have access to all styling properties from SystemIcon.

Layout Component

Toast.Icon supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
fill

The fill color of the SystemIcon. This overrides color.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

size number string undefined

The size of the SystemIcon in px.

styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
background

The background color of the SystemIcon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
childrenReactNode
icon

The icon to display from @workday/canvas-system-icons-web.

accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

backgroundHover

The background color of the SystemIcon on hover.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

div
refReact.Ref<R = div>

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).

Toast.Message

Toast.Message renders our Subtext component where you can style however way you'd like with style properties. This component also has an id so that when the Toast has a prop of mode="dialog" the message is read out by screen readers by adding an aria-describedby on the main Toast component.

Layout Component

Toast.Message supports all props from thelayout component.

Props

Props extend from p. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
variantkeyof

Type variant token names: error, hint or inverse.

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

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
childrenReactNode
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

p
refReact.Ref<R = p>

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).

model

Optional 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(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional 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.

Toast.Link renders our Hyperlink component. If you need to link to more information, use this component.

Props extend from a. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
variant'inverse'

sets modifier styles for Hyperlink - inverse: sets the color to frenchVanilla100 and updates hover, focus, and active pseudo-classes

hrefstring

attribute for the hyperlink URL

childrenReactNode
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

a
refReact.Ref<R = a>

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).

Model

useToastModel

useToastModel (config: ):

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

Can't Find What You Need?

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

FAQ Section