Toaster

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Diese Komponente wird erneut auf Barrierefreiheit getestet. Der vollständige Test steht noch aus und kann erst nach einem abgeschlossenen Release erfolgen.

Wir von KoliBri werden die Toaster-Komponente und den ToasterService mit Version 5 entfernt, da sie mit den bestehenden Barrierefreiheitsvorgaben nicht vereinbar ist. Statt noch mehr Ressourcen in ein wahrscheinlich nie barrierefreies Konzept zu investieren, möchten wir die Energie in die Entwicklung und Dokumentation robuster, barrierefreier Alternativen lenken.
Siehe dazu auch .
In den kommenden Wochen werden wir unsere Beispiele und Dokumentation auf empfehlenswerte Alternativen umstellen, z. B. Inline-Feedback, ARIA-konforme Statusmeldungen, Dialoge für kritische Informationen.

Synonyme: Notification, Snackbar

Beschreibung: Der Toaster-Service bietet eine Möglichkeit, optische Rückmeldungen an Nutzer:innen zu geben. Toasts werden am oberen Rand des Browserfensters angezeigt und können geschlossen werden. Werden mehrere Toasts hintereinander angezeigt, ohne dass die vorherigen geschlossen wurden, werden sie untereinander dargestellt.

Beispiel

Grundlegende Verwendung des ToasterService zur Anzeige einer Toast-Nachricht:

import { ToasterService } from '@public-ui/components';

// Toaster-Instanz für das aktuelle HTML-Dokument abrufen
const toaster = ToasterService.getInstance(document);

// Neue Toast zur Warteschlange hinzufügen
toaster.enqueue({
 label: 'Dies ist der Titel',
 description: 'Dies ist der Inhaltstext der Toast-Nachricht.',
 type: 'info',
});

Barrierefreiheit

⚠️ Wichtig: Der Toaster hat bekannte Barrierefreiheitsprobleme und wird daher mit Version 5 entfernt. Die Verwendung wird nicht empfohlen.

Die Komponente erfüllt nicht die Standards für barrierefreie Benachrichtigungen:

• Toasts werden oft nicht von Screenreadern angekündigt
• Es gibt keine zuverlässige Möglichkeit, Nutzer:innen von Screenreadern auf neue Toasts hinzuweisen
• Die zeitgesteuerte Anzeige und automatische Ausblendung können für Menschen mit vestibülren Störungen problematisch sein

Links und Referenzen

Konstruktion / Technik

Service-Initialisierung

Der Toaster ist kein HTML-Element und wird nicht direkt verwendet. Stattdessen wird der ToasterService verwendet, um eine Toaster-Instanz zu erstellen und zu verwalten:

import { ToasterService } from '@public-ui/components';

// Toaster-Instanz für das aktuelle Dokument erstellen
const toaster = ToasterService.getInstance(document);

Toast hinzufügen

Toasts werden über die Methode enqueue() zur Warteschlange hinzugefügt:

const closeToastFn = await toaster.enqueue({
 label: 'Titel der Toast-Nachricht',
 description: 'Beschreibender Text',
 type: 'info', // 'default', 'info', 'success', 'warning', 'error'
 onClose: () => {
  console.log('Toast wurde geschlossen');
 },
});

// Toast später programmgesteuert schließen
closeToastFn();

Parameter der enqueue()-Methode

Parameter	Typ	Erforderlich	Beschreibung
label	string	Ja	Titel oder Überschrift der Toast-Nachricht
description	string	Nein	Beschreibender Inhaltstext der Toast-Nachricht
type	"default" | "info" | "success" | "warning" | "error"	Nein	Semantische Art der Nachricht (bestimmt das Aussehen)
variant	"card"	Nein	Veraltet. Die Variante ist stets "card"; diese Property wird in einer zukünftigen Version entfernt.
render	(element: HTMLElement, { close: Function }) => void	Nein	Alternative zu description: Benutzerdefinierte Render-Funktion
onClose	() => void	Nein	Callback-Funktion, die aufgerufen wird, wenn die Toast geschlossen wird

Benutzerdefinierte Darstellung

Statt einen statischen description-Text zu verwenden, können Sie eine benutzerdefinierte Render-Funktion bereitstellen:

const closeToastFn = await toaster.enqueue({
 label: 'Benutzerdefinierte Toast',
 render: (element: HTMLElement, { close }) => {
  // Eigenen HTML-Inhalt erstellen
  element.innerHTML = '<p>Dies ist benutzerdefinierter Inhalt</p>';

  // Benutzerdefinierten Close-Button hinzufügen
  const button = document.createElement('button');
  button.textContent = 'Schließen';
  button.addEventListener('click', close, { once: true });
  element.appendChild(button);
 },
});

Service-Verwaltung

Der ToasterService bietet zusätzliche Methoden zur Verwaltung von Toasts:

closeAll(immediate?: boolean): void

Schließt alle aktuell angezeigten Toasts.

// Alle Toasts mit Animation schließen (Standard)
toaster.closeAll();

// Alle Toasts sofort ohne Animation schließen
toaster.closeAll(true);

dispose(): void

Entfernt den Toast-Container aus dem DOM. Die Toaster-Instanz kann danach nicht mehr verwendet werden. Alle angezeigten Toasts werden geschlossen.

toaster.dispose();
// Weitere toaster-Aufrufe sind jetzt nicht mehr möglich

Toast-Typen und deren Bedeutung

In KoliBri unterscheiden wir drei Ebenen für Toast-Konfiguration:

• type → definiert die semantische Bedeutung der Nachricht. Mögliche Werte: "default", "info", "success", "warning", "error"

• variant → steuert das visuelle Erscheinungsbild. Veraltet – die einzig gültige und immer verwendete Variante ist "card".

Verwendungsempfehlungen nach Typ

Typ	Empfehlung	Beispiel
"info"	Neutral informative Meldungen	„Datei wurde hochgeladen"
"success"	Erfolgreiche Operationen	„Änderungen gespeichert"
"warning"	Wichtige Hinweise, die Aufmerksamkeit erfordern	„Diese Aktion kann nicht rückgängig gemacht werden"
"error"	Fehler oder kritische Probleme	„Fehler beim Speichern: Netzwerk nicht verfügbar"
"default"	Neutrale Meldungen ohne spezifische Semantik	Allgemeine Benachrichtigungen