Toast
A short, non-modal message about something the user just did ("Copied", "Saved", "Couldn't save"), or something in progress ("Deleting event…"). Toasts appear in the page's one toast region, go away on their own or when dismissed, and never take focus.
Usage
Render the region once, in the layout, near the end of <body>.
<body>
<%= yield %>
<%= render(Impulse::ToastRegionComponent.new) %>
</body>Show a toast from JavaScript with showToast.
import { showToast } from '@ambiki/impulse-view-components/toast';
showToast('Saved', { variant: 'success' });Arguments
Impulse::ToastRegionComponent
| Name | Default | Description |
|---|---|---|
| placement | :top_center | Where the toasts show: :top_start, :top_center, :top_end, :bottom_start, :bottom_center or :bottom_end. The newest toast is nearest the edge. |
| hotkey | "F8" | The key that moves focus to the newest toast and back. nil turns it off. |
| id | "awc-toast-region" | The region's id. |
Any other keyword arguments are passed to the <awc-toast-region> element as HTML attributes.
Slots
| Name | Description |
|---|---|
| toasts | Toasts to show with the page. Takes Impulse::ToastComponent's arguments. |
Impulse::ToastComponent
| Name | Default | Description |
|---|---|---|
| variant | :info | :info, :success, :warning or :danger. The flash keys :notice (info), :alert and :error (danger) are taken too. Anything else falls back to :info. |
| duration | variant's | How long the toast shows, in milliseconds or as a duration such as 8.seconds. nil keeps it until it is dismissed. Without one, see Timing. |
Any other keyword arguments, such as id, are passed to the <awc-toast> element as HTML attributes. Its content is the message.
Slots
| Name | Description |
|---|---|
| title | A title, shown above the message. |
Examples
Showing a flash as a toast
Render a toast for each flash message. variant: takes the flash keys Rails apps use: notice is info, alert and error are danger, and a variant's own name is that variant.
<% flash_messages = { notice: "Goal created.", alert: "Couldn't email the parents." } %>
<%= render(Impulse::ToastRegionComponent.new) do |region| %>
<% flash_messages.each do |type, message| %>
<% region.with_toast(variant: type) { message } %>
<% end %>
<% end %>Any other key shows as info, so render only the flash keys that hold messages.
Showing a toast from the server
Append a rendered toast to the region, #awc-toast-region, such as from a stream response. It shows as it connects.
<%= render(Impulse::ToastComponent.new(variant: :success)) { "Goal saved." } %>A title
<%= render(Impulse::ToastComponent.new) do |toast| %>
<% toast.with_title { "You're offline" } %>
We kept a copy of your work in this browser.
<% end %>showToast('We kept a copy of your work in this browser.', { title: 'You’re offline' });A toast with rich content
Render the toast in a <template>, and pass the template to showToast. The toast is cloned each time.
<template id="clipboard-toast">
<%= render(Impulse::ToastComponent.new(id: "clipboard-toast-message", variant: :success)) { t(".copied") } %>
</template>showToast(document.getElementById('clipboard-toast'));A toast for a promise
showToast.promise shows a loading toast while a promise is pending, then says how it settled in the same toast: a success toast, which closes on its own, or a danger toast, which stays.
showToast.promise(createEvent(), {
loading: 'Creating event…',
success: (event) => `${event.name} created.`,
error: (error) => `Could not create event: ${error.message}`,
});Updating a toast
Showing a toast with the id of one already showing updates that one in place: its message, title, variant and duration change, its timer starts over, and it is announced again. It stays where it is among the other toasts. Use it for what showToast.promise doesn't cover, such as more steps than pending and settled.
showToast('Uploading 3 files…', { id: 'upload', duration: Infinity });
// Later
showToast('Uploading 2 files…', { id: 'upload', duration: Infinity });
// Later
showToast('Files uploaded', { id: 'upload', variant: 'success' });A toast from a template keeps the template toast's id, so showing it twice updates the first instead of adding a second.
Timing
Info, success and warning toasts hide after 5 seconds. A danger toast, or one holding an action, such as a link or a button other than its close button, stays until it is dismissed: an error the user can't read in time, or an action that disappears, fails WCAG 2.2.1. A duration always wins.
showToast('Copied', { variant: 'success', duration: 2000 });
showToast('Deleting event…', { duration: Infinity });Every toast's timer pauses while the pointer is over the region, while focus is in it, and while the window or the tab is in the background. It then carries on with the time it had left.
An action in a toast must also be available elsewhere on the page: a toast is easy to miss.
Placement
The toasts show at the top centre of the screen, 1rem from its edge. Move the region away from the edge with --awc-toast-region-inset, such as to clear a fixed navbar.
:root {
--awc-toast-region-inset: 72px;
}Over a modal dialog
A modal dialog makes everything outside it inert, so the region moves into the topmost open modal dialog, and back once it closes. Its toasts stay usable, and are announced, while a dialog is open. Don't style the region by where it sits in the page.
Accessibility
- The region is a landmark named "Notifications (F8)". F8 moves focus to the newest toast, and F8 again moves it back.
- Escape on a focused toast asks it to hide. Focus moves to the next toast, or back to where it was after the last. A toast that hides any other way, such as by a press on its close button, returns focus to where it was.
- Screen readers announce a danger toast assertively, and the others politely.
- Each toast shows an icon for its variant, which screen readers skip. Say what happened in the message itself: "Couldn't save the goal", not "Error".
Pages restored from cache
A toast goes away with its page. A page restored from cache shows none of the toasts it had: a message that has to outlive the page is a flash, which the next page shows.
Imports
import { showToast } from '@ambiki/impulse-view-components/toast';@import '@ambiki/impulse-view-components/toast';The styles need Bootstrap's Sass and the base styles loaded first. See Import the styles.