Toasts

On this page

A toast is a short message in the bottom-right corner that confirms something happened ("Settings saved") or reports a problem without blocking the page. It disappears by itself.

Success, info, warning and error toastsSuccess, info, warning and error toasts

Figure 1: Success, info, warning and error toasts; the error has a Try again action

phApp.toast('Settings saved');
phApp.toast('Sync starts in a minute', { tone: 'info' });
phApp.toast('Two tills are offline', { tone: 'warning' });
phApp.toast("Couldn't reach the server", {
  tone: 'error',
  action: { label: 'Try again', onClick: load },
});
OptionDefaultWhat it does
tone'success''success', 'info', 'warning' or 'error': sets the icon and colour
duration4 seconds (7 for errors)How long it stays, in milliseconds. 0 keeps it until it's closed.
actionnoneA button in the toast: { label, onClick }

phApp.toast() returns a function that closes the toast early.

Behaviour

  • Toasts stack in the bottom-right corner, newest at the bottom.
  • The timer pauses while the pointer is over a toast or it has keyboard focus, so it can be read and acted on.
  • Each toast has a close button (read out as "Dismiss").
  • Screen readers announce success, info and warning toasts politely, and error toasts straight away.

React

import { useToast } from 'ph-app-kit-react';

const { showToast } = useToast();
showToast({ message: 'Settings saved', status: 'success' });

PhAppProvider already includes the toast provider.

Guidelines

  • Keep it short: what happened, in a few words. "Store settings saved", not "Success!".
  • Errors say what to do next, and offer Try again when it can help.
  • Don't put anything people must read or act on only in a toast. Errors that stop the page from working belong in a callout.
  • One toast per action. Don't toast every background refresh.