Toast
A short message that appears for a moment, such as "Saved", without interrupting the user.
There is no WAI-ARIA APG pattern for toasts. Toasts are read out through a live region, live in a landmark that the keyboard can reach with a hotkey, and stay while the user is reading them.
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Toast } from '@leve-ui/toast';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';
const MESSAGES = [
{ title: 'Saved', description: 'Your changes were saved.' },
{ title: 'Copied', description: 'The link was copied to the clipboard.' },
{ title: 'Invitation sent', description: 'We emailed the invitation to your teammate.' },
];
// Any component inside the Provider can add toasts
const ShowButton = component$(() => {
const toaster = Toast.useToaster();
const count = useSignal(0);
return (
<button
type="button"
class="toast-default-button"
onClick$={() => {
toaster.add$(MESSAGES[count.value % MESSAGES.length]);
count.value += 1;
}}
>
Show toast
</button>
);
});
// Renders the toasts; put it once, usually at the app root
const Toaster = component$(() => {
const toaster = Toast.useToaster();
return (
<Toast.Region class="toast-default-region">
<Toast.List class="toast-default-list">
{toaster.toasts.value.map((toast) => (
<Toast.Root key={toast.id} toast={toast} class="toast-default-toast">
<Toast.Title class="toast-default-title">{toast.title}</Toast.Title>
<Toast.Description class="toast-default-description">
{toast.description}
</Toast.Description>
<Toast.Close aria-label="Close" class="toast-default-close">
<LuX aria-hidden="true" class="toast-default-icon" />
</Toast.Close>
</Toast.Root>
))}
</Toast.List>
</Toast.Region>
);
});
export default component$(() => {
useStyles$(styles);
return (
<Toast.Provider>
<ShowButton />
<Toaster />
</Toast.Provider>
);
});.toast-default-button {
padding: 8px 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.toast-default-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-default-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Region sits at the bottom-end corner of the viewport (data-placement="bottom-end") */
.toast-default-region {
position: fixed;
right: 16px;
bottom: 16px;
z-index: 50;
width: min(356px, calc(100vw - 32px));
font-family: inherit;
}
.toast-default-region:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-default-list {
position: relative;
margin: 0;
padding: 0;
list-style: none;
}
/*
* The toasts are stacked like cards: index 0 is the newest, in front.
* While the pointer is over the Region or focus is in it (data-expanded), they spread out.
*/
.toast-default-toast {
--toast-y: calc(var(--leve-toast-index) * -12px);
--toast-scale: calc(1 - var(--leve-toast-index) * 0.05);
position: absolute;
right: 0;
bottom: 0;
z-index: calc(100 - var(--leve-toast-index));
display: grid;
grid-template-columns: 1fr auto;
gap: 2px 12px;
box-sizing: border-box;
width: 100%;
padding: 14px 16px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
transform-origin: bottom center;
transform: translateX(var(--leve-toast-swipe-move-x, 0px)) translateY(var(--toast-y))
scale(var(--toast-scale));
/* Show the three newest toasts of the stack */
opacity: clamp(0, 3 - var(--leve-toast-index), 1);
transition:
transform 400ms ease,
opacity 400ms ease;
animation: toast-default-in 400ms ease;
/* Horizontal moves go to the swipe; vertical ones still scroll the page */
touch-action: pan-y;
user-select: none;
}
/* Keeps the pointer over the Region in the gap between expanded toasts */
.toast-default-toast::after {
content: "";
position: absolute;
top: 100%;
right: 0;
left: 0;
height: 12px;
}
/* Behind the front toast, every toast is as tall as the front one */
.toast-default-toast:not([data-front]):not([data-expanded]) {
height: var(--leve-toast-front-height);
overflow: hidden;
}
.toast-default-toast[data-expanded] {
--toast-y: calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px);
--toast-scale: 1;
opacity: 1;
}
.toast-default-toast:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-default-toast[data-swipe="move"] {
transition: none;
}
/* Closing: fade out; after a swipe, also slide out the rest of the way */
.toast-default-toast[data-state="closed"] {
opacity: 0;
transition:
transform 200ms ease,
opacity 200ms ease;
}
.toast-default-toast[data-swipe="end"] {
transform: translateX(calc(var(--leve-toast-swipe-end-x) + 100%)) translateY(var(--toast-y));
}
@keyframes toast-default-in {
from {
opacity: 0;
transform: translateY(100%);
}
}
.toast-default-title {
font-size: 14px;
font-weight: 600;
}
.toast-default-description {
grid-column: 1;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.toast-default-close {
grid-row: 1 / span 2;
grid-column: 2;
align-self: start;
display: inline-flex;
padding: 4px;
border: 0;
border-radius: 4px;
background: transparent;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toast-default-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-default-close:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-default-icon {
width: 16px;
height: 16px;
}
@media (prefers-reduced-motion: reduce) {
.toast-default-toast {
transition: none;
animation: none;
}
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/toastnpm install @leve-ui/toastyarn add @leve-ui/toastbun add @leve-ui/toastpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { Toast } from '@leve-ui/toast'; // or '@leve-ui/core'
<Toast.Provider>
{/* Your app: call Toast.useToaster().add$() anywhere inside */}
<Toast.Region>
<Toast.List>
{toaster.toasts.value.map((toast) => (
<Toast.Root key={toast.id} toast={toast}>
<Toast.Title />
<Toast.Description />
<Toast.Action />
<Toast.Close />
</Toast.Root>
))}
</Toast.List>
</Toast.Region>
</Toast.Provider>
| Part | Element | Description |
|---|---|---|
Toast.Provider | None | Holds the toasts and the settings. Wrap your app with it. |
Toast.Region | <section> | The landmark that holds the toasts. The hotkey moves focus to it. |
Toast.List | <ol> | The list of toasts. |
Toast.Root | <li> | One toast. Takes a toast from useToaster().toasts. |
Toast.Title | <div> | The title. |
Toast.Description | <div> | Optional. The details. |
Toast.Action | <button> | Optional. An action such as Undo. It closes the toast after its onClick$. |
Toast.Close | <button> | Closes the toast. |
Adding Toasts#
Toast.useToaster() returns the toasts and the functions that change them. Call it in any component inside the Provider.
const toaster = Toast.useToaster();
const id = await toaster.add$({ title: 'Uploading', duration: Infinity });
await toaster.update$(id, { title: 'Uploaded', duration: 3000 });
await toaster.dismiss$(id); // or dismiss$() to close all
| Option | Description |
|---|---|
title / description | The text, also used for the announcement. |
type | 'foreground' (default) for results of a user action, announced right away. 'background' for background tasks, announced after the current speech. |
duration | How long the toast stays, in ms. Infinity keeps it until it is closed. Defaults to the Provider's duration. |
data | Your own data for rendering, typed with useToaster<T>(). It must be serializable. |
The toasts are kept in a signal in the Provider's context, not in a module variable: each request on the server has its own toasts, and a toast added on the server shows up on the client.
Stacking#
Each toast outputs CSS variables to stack them like cards and spread them out while the pointer is over the Region or focus is in it (data-expanded). The demo above shows one way:
.toast {
position: absolute;
bottom: 0;
transform: translateY(calc(var(--leve-toast-index) * -12px))
scale(calc(1 - var(--leve-toast-index) * 0.05));
}
.toast[data-expanded] {
transform: translateY(calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px));
}
Examples#
Action#
A toast with a Toast.Action stays until it is closed, so the user has time to reach it. Offer the same action elsewhere on the page too, since the toast goes away.
- report.pdf
- photo.png
- notes.txt
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Toast } from '@leve-ui/toast';
import { LuX } from '@qwikest/icons/lucide';
import styles from './action.css?inline';
// The data your toasts carry, typed through useToaster<T>()
type FileToast = { file: string };
export default component$(() => {
useStyles$(styles);
return (
<Toast.Provider>
<Files />
</Toast.Provider>
);
});
const Files = component$(() => {
const toaster = Toast.useToaster<FileToast>();
const files = useSignal(['report.pdf', 'photo.png', 'notes.txt']);
return (
<div class="toast-action">
<ul class="toast-action-files">
{files.value.map((file) => (
<li key={file} class="toast-action-file">
{file}
<button
type="button"
class="toast-action-button"
onClick$={() => {
files.value = files.value.filter((item) => item !== file);
toaster.add$({ title: 'File deleted', description: file, data: { file } });
}}
>
Delete
</button>
</li>
))}
</ul>
{files.value.length === 0 && <p class="toast-action-empty">No files</p>}
<Toast.Region class="toast-action-region">
<Toast.List class="toast-action-list">
{toaster.toasts.value.map((toast) => (
<Toast.Root key={toast.id} toast={toast} class="toast-action-toast">
<Toast.Title class="toast-action-title">{toast.title}</Toast.Title>
<Toast.Description class="toast-action-description">
{toast.description}
</Toast.Description>
{/* A toast with an Action stays until it is closed */}
<Toast.Action
class="toast-action-undo"
onClick$={() => {
if (toast.data) files.value = [...files.value, toast.data.file];
}}
>
Undo
</Toast.Action>
<Toast.Close aria-label="Close" class="toast-action-close">
<LuX aria-hidden="true" class="toast-action-icon" />
</Toast.Close>
</Toast.Root>
))}
</Toast.List>
</Toast.Region>
</div>
);
});.toast-action {
display: flex;
flex-direction: column;
gap: 8px;
width: 280px;
font-family: inherit;
}
.toast-action-files {
display: flex;
flex-direction: column;
gap: 8px;
margin: 0;
padding: 0;
list-style: none;
}
.toast-action-file {
display: flex;
align-items: center;
justify-content: space-between;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.toast-action-empty {
margin: 0;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}
.toast-action-button {
padding: 4px 10px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.toast-action-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-action-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Region sits at the bottom-end corner of the viewport (data-placement="bottom-end") */
.toast-action-region {
position: fixed;
right: 16px;
bottom: 16px;
z-index: 50;
width: min(356px, calc(100vw - 32px));
font-family: inherit;
}
.toast-action-region:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-list {
position: relative;
margin: 0;
padding: 0;
list-style: none;
}
/*
* The toasts are stacked like cards: index 0 is the newest, in front.
* While the pointer is over the Region or focus is in it (data-expanded), they spread out.
*/
.toast-action-toast {
--toast-y: calc(var(--leve-toast-index) * -12px);
--toast-scale: calc(1 - var(--leve-toast-index) * 0.05);
position: absolute;
right: 0;
bottom: 0;
z-index: calc(100 - var(--leve-toast-index));
display: grid;
grid-template-columns: 1fr auto auto;
gap: 2px 12px;
box-sizing: border-box;
width: 100%;
padding: 14px 16px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
transform-origin: bottom center;
transform: translateX(var(--leve-toast-swipe-move-x, 0px)) translateY(var(--toast-y))
scale(var(--toast-scale));
/* Show the three newest toasts of the stack */
opacity: clamp(0, 3 - var(--leve-toast-index), 1);
transition:
transform 400ms ease,
opacity 400ms ease;
animation: toast-action-in 400ms ease;
/* Horizontal moves go to the swipe; vertical ones still scroll the page */
touch-action: pan-y;
user-select: none;
}
/* Keeps the pointer over the Region in the gap between expanded toasts */
.toast-action-toast::after {
content: "";
position: absolute;
top: 100%;
right: 0;
left: 0;
height: 12px;
}
/* Behind the front toast, every toast is as tall as the front one */
.toast-action-toast:not([data-front]):not([data-expanded]) {
height: var(--leve-toast-front-height);
overflow: hidden;
}
.toast-action-toast[data-expanded] {
--toast-y: calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px);
--toast-scale: 1;
opacity: 1;
}
.toast-action-toast:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-toast[data-swipe="move"] {
transition: none;
}
/* Closing: fade out; after a swipe, also slide out the rest of the way */
.toast-action-toast[data-state="closed"] {
opacity: 0;
transition:
transform 200ms ease,
opacity 200ms ease;
}
.toast-action-toast[data-swipe="end"] {
transform: translateX(calc(var(--leve-toast-swipe-end-x) + 100%)) translateY(var(--toast-y));
}
@keyframes toast-action-in {
from {
opacity: 0;
transform: translateY(100%);
}
}
.toast-action-title {
font-size: 14px;
font-weight: 600;
}
.toast-action-description {
grid-column: 1;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.toast-action-undo {
grid-row: 1 / span 2;
grid-column: 2;
align-self: center;
padding: 6px 10px;
border: 0;
border-radius: 6px;
background: #009dfd;
font: inherit;
font-size: 13px;
font-weight: 500;
color: #ffffff;
cursor: pointer;
}
.toast-action-undo:hover {
background: #006ce9;
}
.toast-action-undo:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-close {
grid-row: 1 / span 2;
grid-column: 3;
align-self: start;
display: inline-flex;
padding: 4px;
border: 0;
border-radius: 4px;
background: transparent;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toast-action-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-action-close:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-icon {
width: 16px;
height: 16px;
}
@media (prefers-reduced-motion: reduce) {
.toast-action-toast {
transition: none;
animation: none;
}
}API Reference#
Provider#
| Prop | Default | Type |
|---|---|---|
| duration | 5000 | number How long a toast stays, in ms. A toast with an Action stays until it is closed. |
| placement | 'bottom-end' | 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' Where the Region is placed. Output as |
| swipeDirection | – | 'up' | 'down' | 'left' | 'right' The direction to swipe a toast away. Defaults to the nearest edge of the placement. |
| swipeThreshold | 50 | number How far a toast must be swiped to close it, in px. |
| hotkey | ['F8'] | string[] The keys that move focus to the Region: |
Region#
| Prop | Default | Type |
|---|---|---|
| label | 'Notifications ({hotkey})' | string The name of the region. |
Also accepts all <section> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast-region | Always present |
data-placement | The Provider's placement |
data-expanded | Present while the pointer is over the Region or focus is in it |
The library does not place the Region: use data-placement or your own class to position it.
List#
No props of its own. Accepts all <ol> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast-list | Always present |
data-placement | The Provider's placement |
data-expanded | Present while the pointer is over the Region or focus is in it |
Root#
| Prop | Default | Type |
|---|---|---|
| toast (required) | – | ToastData The toast to render, from |
Also accepts all <li> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast | Always present |
data-state | "open" | "closed" |
data-type | "foreground" | "background" |
data-placement | The Provider's placement |
data-front | Present on the newest open toast |
data-expanded | Present while the pointer is over the Region or focus is in it |
data-swipe | "move" | "cancel" | "end" while or after swiping |
data-swipe-direction | "up" | "down" | "left" | "right" |
| CSS variable | Value |
|---|---|
--leve-toast-index | The position from the front: 0 is the newest open toast |
--leve-toast-count | The number of open toasts |
--leve-toast-front-offset | The total height of the newer toasts, to spread the stack |
--leve-toast-height | The height of this toast |
--leve-toast-front-height | The height of the front toast, e.g. to make the toasts behind it as tall |
--leve-toast-swipe-move-x / -y | The distance swiped so far, while data-swipe="move" |
--leve-toast-swipe-end-x / -y | The distance swiped, when data-swipe="end" |
When closed, the toast gets data-state="closed" and is removed after its CSS animations and transitions finish, so you can animate it out.
Title#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast-title | Always present |
Description#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast-description | Always present |
Action#
No props of its own. Accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast-action | Always present |
Close#
No props of its own. Accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-toast-close | Always present |
Accessibility#
- When a toast is added, its title and description are announced through a live region that is always on the page: assertive for
foreground, polite forbackground. The toast itself is not a live region, since live regions added to the page are not reliably announced. Toast.Regionis a<section>landmark named "Notifications (F8)". Change the name withlabel;{hotkey}is replaced with the hotkey.- Toasts close on their own only while the user is not on them: the timer pauses while the pointer is over the Region, focus is in it, the window is in the background, or a toast is being swiped. A toast with an Action never closes on its own.
- Give
Toast.Closeanaria-labelwhen it shows only an icon.
Keyboard Interactions#
| Key | Description |
|---|---|
F8 | Moves focus to the Region. Change it with the Provider's hotkey. |
Tab | Moves through the toasts and their buttons. |
Escape | On a toast, closes it and moves focus to the next toast, or the Region. |