toast-queue — Accessible, customizable toast notifications

Set up

Set up toast-queue from npm:

npm set up toast-queue
Copy code

Fast begin

Create a queue and add a toast.

import { ToastQueue } from ‘toast-queue’;

const toastQueue = new ToastQueue();

toastQueue.add(‘Your adjustments have been saved.’);
Copy code

That is it. toast-queue handles the queue lifecycle, positioning, dismissal, interplay states, and screen-reader bulletins for you.

Including toasts

For easy messages, cross a string to .add(). For richer notifications, cross an object containing a title and outline.

Easy message

toastQueue.add(‘Your profile has been up to date.’);
Copy code

Wealthy notification

toastQueue.add({
title: ‘Adjustments saved’,
description: ‘Your profile has been up to date.’,
});
Copy code

With an motion

toastQueue.add(
{
title: ‘Replace accessible’,
description: ‘A brand new model is able to set up.’,
},
{
motion: {
label: ‘Reload’,
onClick: () => location.reload()
},
}
);
Copy code

Controlling the queue

Configure the queue once you create it. You possibly can management the place toasts seem, how lengthy they continue to be seen, and what number of are thought of seen directly.

const toastQueue = new ToastQueue({
place: ‘bottom-end’,
period: 6000,
visibleLimit: 3,
});
Copy code

Place

Select from six logical positions:
top-start, top-center,
top-end, bottom-start,
bottom-center, and bottom-end. You may as well change the place after creating the queue.

const toastQueue = new ToastQueue({
place: ‘top-end’,
});
Copy code

Seen restrict

visibleLimit
controls what number of toasts are thought of seen on the identical time. Extra toasts stay rendered within the queue and are marked hidden
[data-hidden]
till the seen restrict permits them to be proven.

const toastQueue = new ToastQueue({
visibleLimit: 3,
});
Copy code

Per-toast choices

Particular person toasts can customise their conduct by passing choices because the second argument to .add().

toastQueue.add(‘Your adjustments have been saved.’, {
period: 6000,
dismissible: true,
precedence: ‘regular’,
className: ‘my-toast’,
onClose: () => {
console.log(‘Toast closed’);
}
});
Copy code

Disable automated dismissal

Set period to 0 when a toast ought to stay seen till it’s dismissed by the consumer or your utility.

toastQueue.add(
{
title: ‘Import completed’,
description: ‘Your recordsdata are prepared.’,
},
{
period: 0,
}
);
Copy code

Styling

toast-queue
gives the queue conduct, accessibility primitives, interplay states, and wise structural types. It doesn’t impose a visible design system.

Customise the part with the data-part attributes uncovered by the toast markup. Styling hooks and CSS customized properties are additionally accessible for queue-level positioning and interplay results.

toast-queue {
/* … */
&[data-active] { /* … */ }
&[data-position] { /* … */ }
[data-part=”group”] { /* … */ }
[data-part=”item”] { /* … */ }
[data-part=”item”][data-hidden] { /* … */ }
[data-part=”item”][data-peek] { /* … */ }
[data-part=”toast”] { /* … */ }
[data-part=”icon”] { /* … */ }
[data-part=”actions”] { /* … */ }
[data-part=”action-button”] { /* … */ }
[data-part=”close-button”] { /* … */ }
}
Copy code

Positioning

Use logical offset variables to manage the gap from the viewport.

toast-queue {
–tq-offset: 1rem;

/* Or management every axis independently. */
–tq-offset-inline: 1.5rem;
–tq-offset-block: 2rem;
}
Copy code

Presets

Elective CSS presets present ready-made layouts with out taking management away out of your utility.

• checklist— a standard vertical queue the place every toast occupies its personal house.
• stacked— a compact card stack the place hidden toasts peek or overlap behind the energetic toast.

Bundler

import ‘toast-queue/presets/checklist.css’;
import ‘toast-queue/presets/stacked.css’;
Copy code

CDN

<hyperlink rel=”stylesheet” href=”https://cdn.jsdelivr.internet/npm/toast-queue@1/dist/presets/checklist.min.css”>
<hyperlink rel=”stylesheet” href=”https://cdn.jsdelivr.internet/npm/toast-queue@1/dist/presets/stacked.min.css”>
Copy code

Utilizing toast-queue with out a bundler

Load the bundle straight from a CDN. That is helpful for static websites, prototypes, and progressively enhanced functions.

<hyperlink rel=”stylesheet” href=”https://cdn.jsdelivr.internet/npm/toast-queue@1/dist/toast-queue.min.css”>

<script kind=”module”>
import { ToastQueue } from ‘https://cdn.jsdelivr.internet/npm/toast-queue@1/+esm’;

const toastQueue = new ToastQueue();
// …
</script>
Copy code

Accessibility

Toasts are introduced to assistive applied sciences when supported by the browser. The queue additionally manages interplay states so a toast might be inspected or interacted with with out being instantly dismissed.

toast-queue
makes use of trendy browser APIs and progressively enhances them. The place supported animation or transition APIs are unavailable, the toast nonetheless renders and stays practical.

If ariaNotify() is just not accessible, you may load the
@github/arianotify-polyfill
conditionally earlier than creating the queue:

if (typeof HTMLElement.prototype.ariaNotify !== ‘operate’) {
await import(‘@github/arianotify-polyfill’);
}

const toastQueue = new ToastQueue();
Copy code

Want extra?

For examples try the official CodePen assortment.

For the entire API, together with queue choices, toast choices, strategies, properties, and template hooks, see the
API reference.