Preview brand Custom

Toast

A short message about what just happened. It appears at the edge of the screen, is read out, and never takes the focus or sits over the work.

Beta

Show code
js
import { toast } from '@somnia/core/lib/toast.js';

// A Notice, made however the page makes them (SomniaCMS clones a hidden one per tone)
toast(notice, { tone: 'success' });           // goes by itself
toast(notice, { tone: 'error' });             // stays until closed
toast(notice, { tone: 'info', timeout: 0 });  // stays: progress its own code will change or close
notice.remove();                              // closes it, with the leaving motion

When to use it

  • Yes: the result of something the person just did, which they can carry on without reading: saved, published, copied, added.
  • No: a mistake in a field (say it under the field), anything that needs an answer (a modal), or anything they must not miss (a notice in the page).
  • If the page already shows the result, such as a row appearing in a list, it doesn't need a toast as well.

Where it sits

ScreenPlaceWhy
WideBottom right, 16px in, up to 420px wideAway from headings, menus and the start of each line, where the eye is working
Phone (600px and under)Bottom, the screen's width less 12px each sideWithin a thumb's reach, and the close button is a full-size target
Home indicatorRaised by the phone's safe areaSo its lower corners are never under the screen's edge
On-screen keyboardRaised above itA message about what was just typed would otherwise be behind the keys
Open dialogOver it (the top layer)A dialog's own result still shows

More than one

  • Toasts stack, the newest nearest the edge, so the latest news is where the last one was.
  • Three at most. A fourth sends the oldest away, one that would have gone by itself before one that waits to be closed.
  • The same message twice is one toast: the older goes.
  • Something that moves through stages (publishing, then live) is one toast whose words change, not a new one for each stage.

How long it stays

ToneStays
Info, success5 seconds, plus 60 ms for each character past 60, up to 10 seconds. At least 8 seconds when it holds a link or button
Warning, errorUntil closed

The clock stops while the pointer or the keyboard focus is on any toast, and while the page is in a background tab. Every toast has a close button.

Motion

MomentWhat movesTime and curve
ArrivingRises 12px and fades in; its place opens, so the toasts above glide up240 ms, cubic-bezier(.2, .7, .2, 1)
LeavingFades and drops 8px; its place closes, so the others settle180 ms, ease-in
Changing its wordsNothing moves: the words and the colour change in placeNone
Reduced motionA fade only: no rise, no gliding200 ms in, 150 ms out

Words

Do

One or two short sentences, saying what happened and what's next if anything: "Published. Going live: the site usually shows it in a minute or two."

Don't

A heading, a list, or more than one thing to press. If it needs those, it isn't a toast.

Accessibility

What it does for you

  • It never takes the focus: the keyboard stays where the person is working.
  • It is read out when it arrives: the toasts sit in a polite status region, and an error is an alert.
  • Notes and confirmations go by themselves after five seconds or more, longer for longer words. Warnings and errors stay until closed.
  • The clock stops while the pointer or the focus is on any toast, and while the tab is hidden.
  • Every toast has a close button, named "Dismiss this message", 32px square. Escape closes the one the focus is in.
  • When a toast closes with the focus in it, the focus goes to the next toast, or back to where the keyboard was.
  • With reduced motion it fades and does not move.

What you need to do

  • Only for what the person can carry on without reading.
  • Nothing in a toast that exists nowhere else: an error’s way out must also be in the page.
  • Words short enough to read in the time it stays.

Keyboard

KeyWhat it does
TabReaches the toasts after everything else on the page.
Enter or SpaceOn a close button: closes that toast.
EscapeCloses the toast the focus is in.

What a screen reader is told

  • The toast’s words as they arrive, with the hidden first word that says its kind.
  • An error at once, as an alert.

This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.

WCAG 2.2

CriterionLevelHow this meets it
1.4.13 Content on Hover or FocusAAIt can be closed without moving the pointer, and stays while pointed at.
2.2.1 Timing AdjustableAThe ones that go by themselves stop their clock under the pointer or the focus; anything that matters stays until closed.
2.3.3 Animation from InteractionsAAAA fade only, with reduced motion.
2.4.3 Focus OrderAIt never takes the focus, and hands it back when closed from the keyboard.
2.5.8 Target Size (Minimum)AAThe close button is 32px square.
4.1.3 Status MessagesAAA status message, announced without taking the focus.

The criteria this component has a part in. A page that uses it still has to meet the rest.

Checked

CheckHowResult
Automated (axe-core)WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in darkPassed
Nothing found, light or dark
Narrow screenNo sideways scrolling at 320px wide (WCAG 1.4.10)Passed
No sideways scrolling
Keyboard and what the browser reportsReal key presses on the live example, and the role, name and state given to assistive technologyPassed
9 of 9 checks pass
On paperSomnia’s print check: no overlaps, stranded headings or controls on the pagePassed
No faults on 6 sheets
Screen readerListened to by a person, in VoiceOver and NVDANot yet
Not yet checked by a person

The 9 checks made with the keyboard, on the example at the top of this page:

  • Passed A toast arrives without taking the focus
  • Passed The toasts sit in a polite status region; a confirmation is a note and an error an alert
  • Passed Every toast has a close button named "Dismiss this message", at least 24px square
  • Passed A confirmation goes by itself; an error stays until closed
  • Passed The clock stops while the focus is on a toast
  • Passed Escape closes the toast the focus is in, and the focus goes back to where the keyboard was
  • Passed With two toasts, closing one from the keyboard moves the focus to the other’s close button
  • Passed Never more than three at once
  • Passed With reduced motion a toast fades and does not move

Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.

Not yet checked

  • How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
  • Windows high contrast (forced colours) has not been looked at by a person.
  • The toasts come last in the Tab order, after the whole page. Someone using the keyboard has a long way to go to close an error that stays. No shortcut takes them there.
  • A confirmation that goes after five seconds can be missed by someone reading slowly or using a magnifier.

Evidence

Where it's used

WhereFor
Somnia CMSSaved, published, copied and the like; a publish’s progress is one toast that changes in place.

What we saw, and what changed

WhenWhat we sawWhat changed
The editor’s messages appeared in the page and pushed what was being worked on down.Toasts: at the edge of the screen, in the top layer (1.64.0).
In Safari the toasts’ region stretched the height of the window.Its place and height are set outright (1.66.0).
Toasts jumped as others came and went, sat under a phone’s home indicator and keyboard, and every one stayed six seconds whatever its length.A component of its own: they glide, clear the indicator and the keyboard, and stay long enough to read (1.75.0).
Writing this page’s checks: closing a toast from the keyboard left the focus at the top of the page.It goes to the next toast, or back to where the keyboard was (1.86.0).

From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.

What we don't know yet

  • Whether five seconds is long enough has not been tested with anyone.