Toast Notification Library

Worum es geht

Die Bibliothek besteht aus einer Klasse ToastManager plus dünnen Globalen: showToast, dismissToast, clearAllToasts und Kurzformen wie showToast.success(text, options). In der README bewusst ohne npm - Sie binden toast.css und toast.js ein und fertig. So läuft auch die Live-Demo auf statischem Hosting.

Jede Benachrichtigung ist ein div.toast-item mit Aufbau: ein Block .toast-content (Icon-Span + Textabsatz), ein optionales × zum Schließen und optional eine .toast-timer-Leiste, wenn duration grösser null und showTimerBar wahr ist. Container entstehen pro Ecke (oder Mitte): .toast-container.top-right usw. werden beim ersten Gebrauch an document.body gehängt.

Sechs Presets - success, error, warning, info, reminder und custom - haben jeweils Standard-Verlauf und Emoji-Icon in typeConfig. Pro Toast können Sie mit customStyles (Inline-Styles plus optionale Zusatzklasse) nachjustieren oder toast.css für das ganze Projekt anpassen.

• Keine weiteren Runtime-Abhängigkeiten ausser den DOM-APIs des Browsers.
• Escape schliesst alles; der Schließen-Button ruft dismiss mit stopPropagation auf, damit kein Navigationsklick ausgelöst wird.
• Höchstens fünf Toasts pro Position; der älteste wird entfernt, bevor ein neuer kommt.
• duration: 0 lässt den Toast stehen, bis manuell geschlossen (close bleibt massgeblich).
• role="alert", aria-live="polite" und tabindex="0" für unterstützende Technologien.

Die API verwenden

show verschmilzt Ihr Objekt mit Defaults: type info, position top-right, duration 3000 ms, close true, stopOnFocus true, newWindow true, showTimerBar true und ein leeres customStyles-Objekt. Pflicht ist nur text; ohne dieses protokolliert die Bibliothek einen Fehler und gibt null zurück.

destination macht die ganze Toast-Fläche klickbar: ein Klick nutzt window.open mit noopener/noreferrer, wenn newWindow true ist, sonst window.location.href. Icons kommen aus customStyles.icon, falls gesetzt, sonst aus typeConfig für den Typ, mit Sprechblasen-Fallback.

showToast({
  text: "Saved successfully",
  type: "success",
  position: "bottom-right",
  duration: 4000,
  close: true,
  stopOnFocus: true,
  showTimerBar: true,
  destination: "https://example.com/log",
  newWindow: false,
  customStyles: {
    borderRadius: "10px",
    customClass: "site-toast"
  }
});

// Shorthand helpers mirror the same options object
showToast.error("Network failed", { duration: 0, close: true });

Die Convenience-Methoden sind reiner Zucker: Sie verteilen options und setzen den type. Das Timer-Verhalten verbindet das Timeout in startTimer mit der CSS-Breiten-Transition auf .toast-timer, sodass die Leiste linear über remainingTime schrumpft; pauseTimer löscht das Timeout, friert die Breite ein, resumeTimer startet Animation und Timeout mit dem Restbudget neu.

Struktur des Codes

Beim Aufbau initialisiert ToastManager zwei Maps: toasts (numerische ID → { element, config, timer, … }) und containers (Positions-String → DOM-Knoten). init fügt ein Stylesheet-Link für toast.css ein, falls #toast-styles fehlt, und registriert keydown auf document, sodass Escape clearAll auslöst.

createToastElement baut den Baum, verdrahtet Pause bei Hover/Fokus, wenn stopOnFocus wahr und duration positiv ist, und montiert die Timer-Leiste auf Wunsch. getContainer erzeugt faul absolute Flex-Stapel mit Klasse toast-container plus Positionsname. enforceMaxToasts entfernt den frühesten .toast-item im Stapel, bevor maxToasts überschritten wird.

// Merged config + lifecycle (conceptual excerpt)
const config = { ...this.defaults, ...options };
this.enforceMaxToasts(config.position);
const container = this.getContainer(config.position);
const toastElement = this.createToastElement(toastId, config);
container.appendChild(toastElement);
requestAnimationFrame(() => this.animateIn(toastElement, config.position));
if (config.duration > 0) this.startTimer(toastId);

// Published on window after load
const toastManager = new ToastManager();
window.showToast = (options) => toastManager.show(options);

Animationen laufen über Klassen: toast-enter / toast-enter-active (und ggf. from-left / from-center) für den Eintritt; toast-exit / toast-exit-active plus Richtungsklassen to-* für 300 ms Ausgang, bevor der Knoten entfernt wird. applyCustomStyles mappt bekannte Schlüssel aus customStyles auf Inline-Styles und kann customClass anhängen.

• dismiss leert Timeouts, spielt animateOut, entfernt den Knoten und löscht leere Container aus der containers-Map.
• Tastaturfokus innerhalb des Toasts wirkt mit bei Pause/Fortsetzen neben Maus-Hover.
• Der innere Verlauf des Timers ist eine eigene Schicht für ein subtiles Highlight über der schrumpfenden Leiste.

CSS und Theming

toast.css enthält Layout, Stacking, z-index und die Transition-Voraussetzungen, die das JavaScript umschaltet. Weil Typen als Klassen auf .toast-item stehen (z. B. .toast-item.success), können Sie Presets einfärben, ohne JavaScript anzufassen - achten Sie auf passende Spezifität.

Für Kampagnen: customStyles für Einzelanpassungen, globale Overrides für Design-Tokens (Abstand, Schatten, Typo). Positionsklassen müssen zu den Strings von showToast passen: top-left, top-right, bottom-left, bottom-right, center.

/* Stronger success colour sitewide */
.toast-item.success {
  background: linear-gradient(135deg, #059669, #047857);
}

/* Clickable toasts: pointer cursor comes from .clickable */
.toast-item.clickable {
  cursor: pointer;
}

/* Pause state during hover/focus (class added in JS) */
.toast-timer.paused {
  transition: none !important;
}

Ausprobieren und einsetzen

Die interaktive Demo testet Positionen, lange Laufzeiten, Stress und Custom-Styling auf einer Seite - nutzen Sie sie als Regression-Check nach Forks oder Style-Änderungen.

Quellcode und Lizenz liegen auf GitHub unter GPL-3.0. Für Produktion können Sie ausführliche console.log-Ausgaben entfernen, falls Ihr Fork Debug in createToastElement/startTimer behält.