Toast Notifications

Quick Start

1. Add to your HTML <head>:

Code snippet omitted: it ships with the download.

2. Add before the closing </body> tag:

Code snippet omitted: it ships with the download.

3. Add the component markup (the block marked <!-- Component starts here --> in index.html). It is one empty element:

Code snippet omitted: it ships with the download.

data-toast-stack is what the script looks for. data-max-visible (default 3) is how many toasts stay in the column before the rest tuck behind the chip; data-duration (default 4500) is the default lifetime in milliseconds. Everything else is created by the script.

4. Fire a toast:

Code snippet omitted: it ships with the download.

What's Included

• index.html: the demo page, the component markup and the two theme blocks
• assets/style.css: the component, its five type accents and three complete looks
• assets/script.js: readable, commented GSAP core source with the public API and cleanup
• assets/script.min.js: minified production script
• thumbnail.html: build-only capture state

Using It With Your Own Design

What the component needs from your markup: one element carrying data-toast-stack. That is all. It builds its own cards, its own "+N more" chip and its own icons.

What is only the demo's furniture: the toolbar strip (.showcase-toolbar), the short .stage-doc article the toasts land over, and the Google Font link. Delete all of it; none of it is part of what you bought.

CSS the component depends on: do not put a CSS transform on .toast-card or on .toast-progress — GSAP owns those, and a CSS transform underneath one is read as a pixel offset it never returns from. (transform-origin on the progress bar is fine, and the translateX on .toast-stack itself is safe because GSAP never touches the container.) Keep --extra-sign defined: it is 1 when the stack sits at the bottom of the screen and -1 when it sits at the top, and it is how the script knows which way to tuck the collapsed cards without ever reading the variant name.

Themes

Two themes, light and dark, set with one attribute. They are the same design at two token values: every colour, radius, shadow, the type accents and the stack's placement are CSS custom properties defined in body[data-variant="light"] and re-valued in body[data-variant="dark"] in assets/style.css, so the script is identical across both and never reads the attribute.

Code snippet omitted: it ships with the download.

Leaving the attribute off gives you light. The demo's toolbar and the ?variant=dark URL parameter only set this attribute; neither is part of the component.

Re-value for your brand: the ground scale (--ground, --ground-2, --raised, --hover), the ink scale (--ink, --ink-2, --ink-3), the hairlines (--line, --line-strong), the accent pair (--accent, --accent-ink, --accent-text), --shadow, --font and the radii (--radius, --radius-sm, --radius-xs). The five type accents (--type-default/success/error/warning/info/loading) are status colours and stay muted. Placement is four properties (--stack-top/bottom/left/right) plus --stack-direction; if you move a stack to the top of the screen, set --extra-top: 0, --extra-bottom: auto and --extra-sign: -1 with it. Nothing in assets/script.js changes, and no tween hard-codes a colour.

How It Works

The countdown is a tween, not a timeout. Each toast's lifetime is a linear tween scrubbing its progress bar, so it can be paused and resumed: hovering the stack or tabbing into it holds the bar where it stands, and leaving carries on from there. A toast collapsed behind the chip is paused too, because something nobody can read should not be counting down.

Throw it away, or let it spring back. Pointer events track net displacement, so a small wobble is still a tap and the action button keeps working on touch. Past a third of the card's width, or past a velocity threshold, the card is thrown out in the direction it was moving; short of that it springs back on an elastic ease, its x is reset to a real zero and its remaining time resumes.

One card, several states. toast.promise() shows a single loading toast and then rewrites it in place, tweening the card's height from the old measurement to the new one while the icon spins in and the text lifts.

The API

window.toast is the first stack on the page.

Code snippet omitted: it ships with the download.

show() (and every typed shortcut) returns a handle:

Code snippet omitted: it ships with the download.

The promise helper takes a promise (or a function returning one) and morphs one toast through its states. Each message can be a string, an options object, or a function receiving the resolved value or the error:

Code snippet omitted: it ships with the download.

Events. The stack dispatches toast:show, toast:update, toast:action, toast:dismiss, toast:expand and toast:collapse, all bubbling, with detail.id, detail.type and (where it applies) detail.reason and detail.action:

Code snippet omitted: it ships with the download.

window.spawnToast(title, message) is kept from the first release so existing calls keep working.

Accessibility

• Live regions follow the type. An error toast is role="alert" with aria-live="assertive"; every other type is role="status" with aria-live="polite". Both are aria-atomic, so the title and message are read as one notice.
• Keyboard. Every visible toast is a tab stop. Tab reaches it, its action button and its close button; Escape on a focused toast dismisses it; Escape elsewhere in the stack collapses an expanded pile. The "+N more" chip is a real button with aria-expanded.
• Focus is never stranded. Dismissing a focused toast moves focus to the neighbouring toast, or back to whatever was focused before you entered the stack if that was the last one.
• The countdown pauses on focus-within, not just on hover, so a keyboard user gets the same reading time a mouse user does.
• Collapsed toasts are aria-hidden and out of the tab order while they are tucked behind the chip, so screen reader users are not walked through cards they cannot see.
• Coarse pointers get no hover-only state: the chip expands the pile on tap, and the close and action targets grow.
• Under prefers-reduced-motion: reduce toasts appear and leave without animation, the loading spinner and the indeterminate bar stop, and the countdown still runs.

Customisation

• Colours, radii, shadows, the five type accents and the stack's placement are custom properties on each body[data-variant] block in assets/style.css.
• Timings and eases are the gsap.to / gsap.fromTo calls in assets/script.js; the dismiss thresholds are the two lines in attachDrag.
• The expanded pile shows up to twice data-max-visible toasts, so a stack can never grow taller than the screen; that multiplier is visibleLimit().

Requirements

• GSAP 3.12+ (the demo uses 3.15.0; core only, no plugins)
• No build step, no framework