toast-queue by André Ruffert

Live playground

Toast notifications

Try toast-queue in the browser. Framework-agnostic, customizable, and built on modern web APIs with progressive enhancement and graceful fallbacks.

Toasts: 0

Playground

Queue controls

Change how the toast queue behaves.

Behavior
Appearance

toast-queue provides behavior and accessibility primitives. The visual presentation is yours to customize.

Customize CSS

Copy code

Documentation

Using toast-queue

Add accessible toast notifications to any modern web app with a small, framework-agnostic API. Start with the quick example, then customize the queue and presentation to match your application.

Install

Install toast-queue from npm:

npm install toast-queue Copy code

Quick start

Create a queue and add a toast.

import { ToastQueue } from 'toast-queue'; const toastQueue = new ToastQueue(); toastQueue.add('Your changes have been saved.'); Copy code

That's it. toast-queue handles the queue lifecycle, positioning, dismissal, interaction states, and screen-reader announcements for you.

Adding toasts

For simple messages, pass a string to .add(). For richer notifications, pass an object containing a title and description.

Simple message

toastQueue.add('Your profile has been updated.'); Copy code

Rich notification

toastQueue.add({ title: 'Changes saved', description: 'Your profile has been updated.', }); Copy code

With an action

toastQueue.add( { title: 'Update available', description: 'A new version is ready to install.', }, { action: { label: 'Reload', onClick: () => location.reload() }, } ); Copy code

Controlling the queue

Configure the queue when you create it. You can control where toasts appear, how long they remain visible, and how many are considered visible at once.

const toastQueue = new ToastQueue({ position: 'bottom-end', duration: 6000, visibleLimit: 3, }); Copy code

Position

Choose from six logical positions: top-start, top-center, top-end, bottom-start, bottom-center, and bottom-end. You can also change the position after creating the queue.

const toastQueue = new ToastQueue({ position: 'top-end', }); Copy code

Visible limit

visibleLimit controls how many toasts are considered visible at the same time. Additional toasts remain rendered in the queue and are marked hidden [data-hidden] until the visible limit allows them to be shown.

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

Per-toast options

Individual toasts can customize their behavior by passing options as the second argument to .add().

toastQueue.add('Your changes have been saved.', { duration: 6000, dismissible: true, priority: 'normal', className: 'my-toast', onClose: () => { console.log('Toast closed'); } }); Copy code

Disable automatic dismissal

Set duration to 0 when a toast should remain visible until it is dismissed by the user or your application.

toastQueue.add( { title: 'Import finished', description: 'Your files are ready.', }, { duration: 0, } ); Copy code

Styling

toast-queue provides the queue behavior, accessibility primitives, interaction states, and sensible structural styles. It does not impose a visual design system.

Customize the component with the data-part attributes exposed by the toast markup. Styling hooks and CSS custom properties are also available for queue-level positioning and interaction effects.

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 control the distance from the viewport.

toast-queue { --tq-offset: 1rem; /* Or control each axis independently. */ --tq-offset-inline: 1.5rem; --tq-offset-block: 2rem; } Copy code

Presets

Optional CSS presets provide ready-made layouts without taking control away from your application.

  • list— a conventional vertical queue where each toast occupies its own space.
  • stacked— a compact card stack where hidden toasts peek or overlap behind the active toast.

Presets are layered under @layer toast-queue, so your own styles can override them.

Bundler

import 'toast-queue/presets/list.css'; import 'toast-queue/presets/stacked.css'; Copy code

CDN

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/toast-queue/dist/presets/list.min.css"> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/toast-queue/dist/presets/stacked.min.css"> Copy code

Using toast-queue without a bundler

Load the package directly from a CDN. This is useful for static sites, prototypes, and progressively enhanced applications.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/toast-queue/dist/toast-queue.min.css"> <script type="module"> import { ToastQueue } from 'https://cdn.jsdelivr.net/npm/toast-queue/+esm'; const toastQueue = new ToastQueue(); // ... </script> Copy code

Accessibility

Toasts are announced to assistive technologies when supported by the browser. The queue also manages interaction states so a toast can be inspected or interacted with without being immediately dismissed.

toast-queue uses modern browser APIs and progressively enhances them. Where supported animation or transition APIs are unavailable, the toast still renders and remains functional.

If ariaNotify() is not available, you can load the @github/arianotify-polyfill conditionally before creating the queue:

if (typeof HTMLElement.prototype.ariaNotify !== 'function') { await import('@github/arianotify-polyfill'); } const toastQueue = new ToastQueue(); Copy code

Need more?

For the complete API, including queue options, toast options, methods, properties, and template hooks, see the API reference.