Toaster
Short messages at the bottom of the page that tell the user an action is done, and let them undo it. toast() shows one from anywhere, also outside components.
When to use
- To tell that something was done, when the page itself doesn't show it clearly: saved, copied, sent.
- With
undo, instead of asking for confirmation before an action that can be reverted: it saves the user a click. For those that can't, use Confirm. - Not for errors in a form: show them next to the field.
Examples
Undo
With undo, the toast shows an undo button and stays 7 seconds. ⌘Z or Ctrl+Z undoes the newest one too, except while typing in a field, where it's the field's own undo. Afterwards, a toast says it was undone; if the function throws, a danger one says it couldn't.
<LnxButton @click="save()">Save</LnxButton>import { toast } from 'lnxjs-components';
const id = toast('Receipt saved', { undo: () => deleteReceipt() }); // returns the id2
3
Variants
variant takes the variants of the button. Danger ones stay 9 seconds and are read out at once by screen readers.
<LnxButton variant="danger" @click="fail()">Fail</LnxButton>
<LnxButton variant="success" @click="toast('Sent to the 12 members', { variant: 'success' })">Send</LnxButton>
<LnxButton variant="info" @click="toast('Copied', { variant: 'info', duration: 2000 })">Copy</LnxButton>2
3
Duration and closing
By default, a toast stays 4 seconds, 7 with undo and 9 if it's danger. The bar at the bottom shows the time left and stops while the toast is pointed at or focused. duration: Infinity keeps it until it's closed.
import { dismiss, toast, undo, toasts } from 'lnxjs-components';
const id = toast('Uploading…', { duration: Infinity });
dismiss(id);
await undo(); // the given one, or the newest that can be undone; resolves to whether there was one
toasts; // the toasts on screen, reactive2
3
4
5
6
Errors when undoing
To log the errors of every undo in one place, pass onUndoError to createLnx. The texts of the buttons and messages come from there too.
app.use(createLnx({ onUndoError: error => reportError(error) }));Host
The toasts live in <LnxToaster />, which is added to the page with the first toast(). If you prefer to place it yourself, render it once in App.vue and no other will be added.
<template>
<RouterView />
<LnxToaster />
</template>2
3
4
Accessibility
- The list is an
aria-live="polite"region: screen readers read each toast when it comes, and danger ones at once, as alerts. - The close button is named with the
closetext, and the undo shortcut is a visual hint next to its button. - With reduced motion, toasts only fade.
Types
ToastOptions
export interface ToastOptions {
variant?: ButtonVariant; /* Color and icon. By default, grayscale */
duration?: number; /* Milliseconds it stays. By default, 4s, 7s with undo and 9s for danger. Infinity keeps it until it's closed */
undo?: () => unknown; /* Shows an undo button, also with ⌘Z or Ctrl+Z. It can return a promise */
}2
3
4
5
Toast
export interface Toast extends ToastOptions {
id: number;
message: string;
variant: ButtonVariant;
duration: number;
}2
3
4
5
6