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.
Show code
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
| Screen | Place | Why |
|---|---|---|
| Wide | Bottom right, 16px in, up to 420px wide | Away 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 side | Within a thumb's reach, and the close button is a full-size target |
| Home indicator | Raised by the phone's safe area | So its lower corners are never under the screen's edge |
| On-screen keyboard | Raised above it | A message about what was just typed would otherwise be behind the keys |
| Open dialog | Over 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
| Tone | Stays |
|---|---|
| Info, success | 5 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, error | Until 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
| Moment | What moves | Time and curve |
|---|---|---|
| Arriving | Rises 12px and fades in; its place opens, so the toasts above glide up | 240 ms, cubic-bezier(.2, .7, .2, 1) |
| Leaving | Fades and drops 8px; its place closes, so the others settle | 180 ms, ease-in |
| Changing its words | Nothing moves: the words and the colour change in place | None |
| Reduced motion | A fade only: no rise, no gliding | 200 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
| Key | What it does |
|---|---|
| Tab | Reaches the toasts after everything else on the page. |
| Enter or Space | On a close button: closes that toast. |
| Escape | Closes 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
| Criterion | Level | How this meets it |
|---|---|---|
| 1.4.13 Content on Hover or Focus | AA | It can be closed without moving the pointer, and stays while pointed at. |
| 2.2.1 Timing Adjustable | A | The 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 Interactions | AAA | A fade only, with reduced motion. |
| 2.4.3 Focus Order | A | It never takes the focus, and hands it back when closed from the keyboard. |
| 2.5.8 Target Size (Minimum) | AA | The close button is 32px square. |
| 4.1.3 Status Messages | AA | A 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
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 9 of 9 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not 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
| Where | For |
|---|---|
| Somnia CMS | Saved, published, copied and the like; a publish’s progress is one toast that changes in place. |
What we saw, and what changed
| When | What we saw | What 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.