Toast - Elements

Toasts are brief user feedback messages that overlay content.

AndroidreleasedElementsreleasediOSreleasedReact 19released

AndroidElementsiOSReact 19

Example theme:

DBA lightFinn lightTori lightBlocket lightNeutral lightVend lightDBA darkFinn darkTori darkBlocket darkNeutral darkVend dark

Accessibility

From an accessibility perspective, toasts should never contain interactive elements, as these should always appear in the same location as the action that triggered them.

Auto-clearing toasts based on a timeout violate WCAG 2 success criteria 2.2.1, unless the information they contain is either redundant (i.e. also available elsewhere in a persistent manner) or insignificant to all people.

You are also advised to avoid putting information in a toast that cannot be re-accessed in any other way due to the impermanent nature of the current toast implementation.

Because of these points we consider the use of toasts to be somewhat of an anti-pattern, and recommend exploring alternative approaches wherever possible. That said, you may still use toasts, as long as you avoid interactive elements like links or close buttons.

Usage

You should not use the toast components directly. Instead use the JavaScript API exported from Warp Elements to create, update and remove toasts

import { toast } from '@warp-ds/elements/toast';

const showBtn = document.getElementById("toast-btn");
showBtn.onclick = () => {
    toast("Toasts are somewhat of an anti-pattern");
};

Dismissable toast

The toast automatically closes by default, so you don't need to have a close button.

From an accessibility perspective, toasts should never contain interactive elements such as close buttons, as interactive elements should always appear in the same location as the action that triggered them.

It might be tempting to use this option and a high duration if you have a warning or error toast to "solve" the WCAG 2 success criteria 2.2.1, but please consider showing warnings and errors as a persistent Alert instead.

If the toast absolutely must be dismissible by the user, set the canclose property to true.

toast('message goes here', { type: 'success', canclose: true });

Examples

Success / positive

This is the default.

Warning

If the user should be warned about something, a toast is probably not the right way to do so. Consider an Alert instead.

A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for warnings).

Error / negative

If the user should be told about an error, a toast is probably not the right way to do so. Consider an Alert instead.

A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for errors).

API Documentation

toast

import { toast } from '@warp-ds/elements/toast';

const theToast = toast('Toasts are somewhat of an anti-pattern');

Returns ToastOptions, which includes the ID you need for updateToast and removeToast.

If you can't pass the result from toast to where you call updateToast or removeToast you can set a known ID manually.

toast('Toasts are somewhat of an anti-pattern', {
    id: 'something-unique-but-stable',
});

Parameter	Type	Summary
message	string	The text content
options	ToastOptions (optional)

updateToast

import { toast, updateToast } from '@warp-ds/elements/toast';

const theToast = toast('The toast function returns an ID');

updateToast(theToast.id, 'Use it to update the text');

Returns ToastOptions.

Parameter	Type	Summary
id	string	The ID of the toast you want to update
message	string	The new text content
options	ToastOptions (optional)

removeToast

Toasts disappear after a set time, but if you need to remove one before that happens you can do so.

import { toast, removeToast } from '@warp-ds/elements/toast';

const theToast = toast('The toast function returns an ID');

removeToast(theToast.id);

Types

ToastOptions

Name	Type	Default	Summary
id	string	Random	Random generated unique ID for the toast element
type	ToastVariants	'success'	Visual style of the toast
text	string	-	The given toast message
duration	number	5000	Duration of toast in milliseconds
canclose	boolean	false	See Dismissable toast

ToastVariants

'success' | 'warning' | 'error'

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system