import { ToastProvider } from '@uhg-abyss/web/ui/Toast';Overview
Toast is a notification system designed to provide feedback to users in a non-intrusive way. To use the Toast component, you need to wrap your application with the ToastProvider component. This provider manages the state and rendering of toasts.
It is recommended to place it inside the ThemeProvider to ensure consistent styling across your application.
import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';import { ToastProvider } from '@uhg-abyss/web/ui/Toast';
function Demo() { return ( <ThemeProvider> <ToastProvider /> <App /> </ThemeProvider> );}Methods
All methods can be accessed via the useToast hook and can be used in any part of your application:
import { useToast } from '@uhg-abyss/web/hooks/useToast';
const { toast } = useToast();toast.show- adds given toast to toasts list or queue depending on current state. Message is required.toast.update- updates toast that was previously added to the state or queue. Message is required.toast.hide- removes toast with given id from toasts state and queue. Id is required.toast.clean- removes all toasts from toasts state and queuetoast.cleanQueue- removes all toasts from queue
Toast props
Each toast state item can have these properties:
id- toast ID, used to update and remove a toast. By default, this ID is randomly generatedtitle- toast title, displayed above the messagemessage- required toast bodytype- style of toast and icons:'info','success','warning'and'error'withCloseButton- determines whether close button should be visiblebackground- background style of toast:'saturated'or'tint'onClose- calls when toast is unmountedautoClose- defines a timeout in ms on which toast will be automatically closed, usefalseto disable auto closeicon- override default iconhideIcon- flag to hide the left icononOpen- calls when toast is mountedcta- an object where a custom CTA can be passed in (see CTA example below)
When showing or updating a toast, all properties except message are optional.
import { IconSymbol } from '@uhg-abyss/web/ui/IconSymbol';import { useToast } from '@uhg-abyss/web/hooks/useToast';
const { toast } = useToast();
// Bare minimum - message is required for all toaststoast.show({ message: 'Hello' });
// Most used toast propstoast.show({ id: 'hello-there', withCloseButton: true, onClose: () => console.log('unmounted'), onOpen: () => console.log('mounted'), autoClose: 5000, title: 'Toast title', message: 'Toast message', type: 'info', background: 'saturated', icon: <IconSymbol icon="home" />,});Usage examples
Type and background
The toast notification supports different visual styles using the type prop (default: 'error'). The available types are:
'info': For informational messages.'success': Indicates a successful operation.'warning': Alerts the user about potential issues.'error': Denotes a problem or critical error.
In addition, the background prop offers two style options:
'saturated': A bold, vibrant background for higher emphasis. This is the default.'tint': A softer, lighter background for a subtle appearance.
Below is an example demonstrating how to generate toasts with each type and background variation:
Closing props
You can pass two different props related to closing:
autoClose: Accepts either a number or a boolean. If given a number, the toast will automatically close after that many milliseconds. If givenfalse, the toast will not auto-close. The default is5000. This prop can be passed in with theshoworupdatemethods explained above.withCloseButton: By defaulttrue, allows you to hide/display the close button at the top right of the toast.
Note: Avoid setting both autoClose and withCloseButton to false. The fourth example below showcases this scenario that you must avoid. See the Accessibility tab for more info.
CTA
Use the cta prop to add a call to action to the Toast. The cta prop accepts an object of the following type:
{ type: 'button' | 'link', props: ButtonProps | LinkProps,}ButtonProps and LinkProps are objects that accept most props of the Button and Link components, respectively, except for size, which is set by the Toast and cannot be altered.
Updating existing toast
You can update an existing toast by targeting the id using the update method.
Position
ToastProvider renders the toasts' container with fixed position inside a React Portal at the bottom right of the screen. On mobile, the toasts will be displayed from the top center. The position cannot be changed.
State and queue
ToastProvider uses a queue hook to manage state. There is no limit for the toasts in the queue; these will accumulate until they are auto-closed or manually removed.
Note: Whenever the amount of toasts reaches the visual height limit of the container, the container becomes scrollable and a "Clear all" button appears at the top right.
Clear state and queue
To remove specific toast from state or queue, use toast.hide function:
toast.show({ id: 'hello', message: 'Hello!' });toast.hide('hello');Use the toast.cleanQueue function to remove all toasts that are not currently displayed, and the toast.clean function to remove all toasts from state and queue.
Toast Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
background | "saturated" | "tint" | 'saturated' | - | The background style of the toast. |
button | { label: string; onClick: () => void; } | - | - | The button to be displayed in the toast. It takes in a label and an onClick function. |
children | React.ReactNode | - | - | The content of the toast. |
className | string | - | - | CSS class name to apply to each element within the component |
closeButtonProps | Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "color"> | - | - | Props for the close button element. |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
cta | { type: "button"; props: ToastButton; } | { type: "link"; props: ToastLink; } | - | - | If present, the Toast will display a button or a link |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | false | - | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. |
hideIcon | boolean | false | - | Whether to hide the icon in the toast. |
icon | React.ReactNode | - | - | The custom icon for the toast. |
onClose | () => void | - | - | Event handler for closing the toast. |
setFocus | (flag: boolean) => void | - | - | Add setFocus so it can be passed from parent components |
title | string | - | - | The title of the toast. |
type | "error" | "info" | "warning" | "success" | 'error' | - | The type of the toast (error, warning, info, success). |
withCloseButton | boolean | true | - | Whether to display a close button on the toast. |
Below are the link(s) to the relevant GitHub type files:
Toast Classes
| Class Name | Description |
|---|---|
| .abyss-toast-root | Root element for the toast |
| .abyss-toast-container | Container element for the toast |
| .abyss-toast-icon-container | Container for wrapping the toast icon |
| .abyss-toast-icon | Icon element displayed in the toast |
| .abyss-toast-body | Wrapper for the toast content |
| .abyss-toast-text-container | Container for the toast texts, including title and description |
| .abyss-toast-heading-container | Container for the toast heading section (title and close icon) |
| .abyss-toast-title | Text element for the toast title |
| .abyss-toast-close-icon | Close icon element to dismiss the toast |
| .abyss-toast-description | Element displaying the toast descriptive text |
| .abyss-toast-cta-container | Toast CTA container |
| .abyss-toast-cta-button | Toast CTA button element |
| .abyss-toast-cta-link | Toast CTA link element |
Toast elements should never present content that is mandatory reading. Toast messages should always be short and concise.
Toasts that close automatically are more accessible than those that require manual interaction. Accessing Toasts by keyboard is difficult. Avoid placing interactive elements within Toasts.
To ensure the best user experience, it's strongly recommended to either enable auto-closing (autoclose is defined)
or provide a close button (withCloseButton is set to true).
Setting both autoClose and withCloseButton to false results in a permanent, non-dismissible Toast, which goes against the concept of a Toast as a temporary, non-modal dialog.
Should you choose to keep the Toast open indefinitely and non-dismissible, be mindful of accessibility concerns and ensure there are alternative means to remove the Toast.
Toast Utilizes the WAI-ARIA Log role. There is no WAI-ARIA standard for toast. Look at the links below for toast accessibility references.
It is suggested to include the hidden keyboard shortcut (Accesskey -A) on sticky toasts.
- Sheri Byrne-Haber: Designing Toast Messages for Accessibility
- Scott O'Hara: A toast to an accessible toast...
- Adrian Roselli: Defining ‘Toast’ Messages
BrAT Accesskey Variations
Windows
- Chrome: Alt + A
- Edge: Alt + A
- Firefox: Alt + Shift + A
MacOS
- Safari
- Without VoiceOver: Control + Option + A
- With VoiceOver: Control + A
- Chrome
- Without VoiceOver: Control + Option + A
- With VoiceOver: Control + Option + Tab (enables pass-through mode) then Control + Option + A
For more information about accesskey BrAT implementations see: Accesskey Accessibility Demo (pauljadam.com)
Reduced Motion
Animations and transitions that have been changed when a user has prefers-reduced-motion set to reduced:
- Left/right slide transitions for queue display and updates have been removed
Keyboard Interactions
| Key | Description |
|---|---|
| Escape | Closes the current toast and moves focus accordingly. |
| Accesskey -A | Jump to (last) toast |
Component Tokens
Note: Click on the token row to copy the token to your clipboard.
Toast Tokens
| Token Name | Value | |
|---|---|---|
| toast.color.border.container.tint.success | #007000 | |
| toast.color.border.container.tint.info | #126ECF | |
| toast.color.border.container.tint.warning | #C24E14 | |
| toast.color.border.container.tint.error | #990000 | |
| toast.color.icon.close.saturated.rest | #FFFFFF | |
| toast.color.icon.close.saturated.hover | #F3F3F3 | |
| toast.color.icon.close.saturated.active | #E5E5E6 | |
| toast.color.icon.close.tint.rest | #4B4D4F | |
| toast.color.icon.close.tint.hover | #323334 | |
| toast.color.icon.close.tint.active | #000000 | |
| toast.color.icon.status.success | #007000 | |
| toast.color.icon.status.info | #126ECF | |
| toast.color.icon.status.warning | #C24E14 | |
| toast.color.icon.status.error | #990000 | |
| toast.color.icon.status.saturated | #FFFFFF | |
| toast.color.surface.container.saturated.success | #007000 | |
| toast.color.surface.container.saturated.info | #196ECF | |
| toast.color.surface.container.saturated.warning | #C24E14 | |
| toast.color.surface.container.saturated.error | #990000 | |
| toast.color.surface.container.tint.success | #F0F9ED | |
| toast.color.surface.container.tint.info | #EEF4FF | |
| toast.color.surface.container.tint.warning | #FFFBEB | |
| toast.color.surface.container.tint.error | #FCF0F0 | |
| toast.color.surface.clear-button.rest | #FFFFFF | |
| toast.color.surface.clear-button.hover | #F3F3F3 | |
| toast.color.surface.clear-button.active | #E5E5E6 | |
| toast.color.text.heading.saturated | #FFFFFF | |
| toast.color.text.heading.tint | #323334 | |
| toast.color.text.label.clear-button | #196ECF | |
| toast.color.text.paragraph.saturated | #FFFFFF | |
| toast.color.text.paragraph.tint | #323334 | |
| toast.border-radius.all.container | 8px | |
| toast.border-radius.all.clear-button | 500px | |
| toast.border-width.all.container | 1px | |
| toast.spacing.gap.vertical.header | 4px | |
| toast.spacing.gap.vertical.content | 8px | |
| toast.spacing.gap.horizontal.container | 8px | |
| toast.spacing.gap.horizontal.header | 16px | |
| toast.spacing.padding.all.container | 16px | |
| toast.spacing.padding.horizontal.clear-button | 16px | |
| toast.spacing.padding.vertical.clear-button | 4px | |
| toast.elevation.container | 0px 8px 24px -2px rgba(0,0,0,0.16) |