Arbeiten mit Sonner
Erstantwort
Wenn dieses Skill zum ersten Mal ohne eine spezifische Frage aufgerufen wird, antworte nur mit:
Ich bin bereit, Ihnen bei der Einrichtung, dem Styling und der Fehlerbehebung von Sonner zu helfen. Mein Wissen stammt vom Autor Emil Kowalski.
Gib keine weiteren Informationen, bis der Benutzer eine Frage stellt.
Ein Anleitungs-Skill für Sonner, die Toast-Bibliothek. Wenn eine Aufgabe Sonner betrifft – Einrichtung, Anzeige von Toasts, Styling oder Fehlerbehebung – antworte zuerst aus dieser Datei. Vollständige Prop-Tabellen für <Toaster /> und toast() befinden sich in API.md; lies sie, wenn du einen genauen Prop-Namen, -Typ oder -Standardwert benötigst.
Einrichtung
Zwei Teile, und nur zwei:
- Ein
<Toaster />, einmal eingebunden, so nah wie möglich an der Wurzel (in Next.js:layout.tsx– es funktioniert innerhalb von Server-Komponenten). Binde es niemals pro-Seite oder bedingt ein; ein zweiter eingebundener Toaster dupliziert jeden Toast. toast()aus Client-Code aufgerufen – Event-Handler, Effekte, Callbacks. Es ist eine einfache Funktion, kein Hook oder Provider erforderlich, aber sie tut nichts auf dem Server: Gib in einer Server-Action das Ergebnis zurück und rufetoast()im Client-Code auf, der es empfängt.
import { Toaster } from 'sonner'; // einmal, im Layout
import { toast } from 'sonner'; // überall client-seitig
Die richtige Methode auswählen
| Gewünscht | Aufruf |
|---|---|
| Einfache Nachricht | toast('Titel') – füge { description } für eine zweite Zeile hinzu |
| Erfolgs-/Fehler-/Info-/Warnungssymbol | toast.success('…'), toast.error('…'), usw. |
| Ladeanzeige, während du den Status selbst verwaltest | toast.loading('…'), aktualisiere dann per ID |
| Laden → Erfolg/Fehler, verknüpft mit einem Promise | toast.promise(promise, { loading, success, error }) – success/error akzeptieren Funktionen, die den aufgelösten Wert/Fehler erhalten |
| Schaltfläche, die etwas tut | { action: { label, onClick } } – schließt den Toast, es sei denn, onClick ruft event.preventDefault() auf; cancel ist die sekundäre Variante |
| Benutzerdefiniertes JSX, standardmäßiger Toast-Rahmen | toast(<jsx />) |
| Benutzerdefiniertes JSX, überhaupt keine Stile | toast.custom((t) => <jsx />) – Headless, t gibt dir die ID zum Schließen |
Rezepte
Einen Toast aktualisieren – rufe toast() erneut mit derselben id auf; nur die Props, die du übergibst, ändern sich. Der Wechsel zu toast.success(…, { id }) ändert den Typ. So funktionieren Lade-zu-Erfolg-Abläufe ohne toast.promise:
const id = toast.loading('Wird hochgeladen…');
toast.success('Hochgeladen', { id });
Beibehalten – { duration: Infinity }. Schließen – toast.dismiss(id) oder toast.dismiss() für alle. Aktive Toasts lesen – useSonner() in React, toast.getActiveToasts() außerhalb.
Links oder Komponenten im Text – übergib eine Funktion für den Titel oder die Beschreibung: toast(() => <a href="…">Ansehen</a>).
Mehrere Toaster – gib jedem eine id und ziele mit toast('…', { toasterId: 'canvas' }). Ohne toasterId rendert jeder Toaster den Toast.
Schließen-Callbacks – onDismiss feuert bei Schließen-Button oder Wischen; onAutoClose feuert bei Timeout. Sie sind getrennt; es gibt keinen einzelnen „geschlossen"-Callback.
Styling – die Eskalationsleiter
Steige nur so weit hinauf, wie es die Änderung erfordert; zu früh zur obersten Sprosse zu springen ist in Ordnung (es ist der empfohlene Endzustand), in der Mitte zu verweilen nicht.
- Standardwerte – plus
richColorsam Toaster für bunte Erfolgs-/Fehleranzeigen,invertzum Umdrehen gegen das Theme. - Inline-Anpassungen –
toastOptions={{ style: {…} }}am Toaster für alle Toasts oderstyleprotoast()-Aufruf. - Klassen an Teilen –
toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}. Sonners eingefügte Stile gewinnen die Kaskade, daher benötigt jede Klasse!important(Tailwind:!text-red-900). Wenn du mehr als ein paar Dinge als important markierst, hör auf – gehe Headless. - Headless –
toast.custom()mit eigenem JSX, wobei Sonners Positionierung, Stapelung und Wischfunktion erhalten bleiben. Der empfohlene Ansatz für einen Design-System-Toast: Kapsle ihn in deiner eigenentoast()-Abstraktion. (unstyled: trueexistiert als Zwischenlösung, aber Headless gibt bei gleichem Aufwand mehr Kontrolle.)
Symbole – tausche Standard-Symbole pro Typ mit der icons-Prop am Toaster aus, pro Toast mit icon, entferne sie mit null.
Theme – theme standardmäßig 'light' und verfolgt nicht das Betriebssystem. Übergib theme="system" oder kopple deinen Theme-Provider: <Toaster theme={resolvedTheme} /> von next-themes.
Fehlerbehebung
| Symptom | Ursache → Lösung |
|---|---|
| Toast erscheint nie | Kein <Toaster /> eingebunden, oder er wurde ausgehängt (bedingtes Rendern, platzierung pro Seite). Binde einen an der Wurzel ein. Bei Aufruf aus einer Server-Action: toast() ist nur clientseitig – rufe es mit dem Ergebnis der Action auf dem Client auf. |
| Gleicher Toast erscheint doppelt | Zwei Toaster eingebunden (Layout und Seite) – behalte einen. Oder toast() in einem Effekt unter React StrictModes doppeltem Aufruf im Entwicklungsmodus – rufe stattdessen im Event-Handler auf oder übergib eine stabile id, sodass der zweite Aufruf aktualisiert statt dupliziert. |
| Tailwind/CSS-Klassen haben keine Wirkung | Standard-Stile überschreiben sie. Markiere sie mit !important oder verwende unstyled / Headless (siehe Leiter oben). |
| Toasts werden völlig ohne Styling gerendert (häufig in Astro, View Transitions) | Sonners eingefügtes Stylesheet ging verloren – importiere es explizit in einem Layout: import 'sonner/dist/styles.css'. |
| Ohne Styling im Shadow DOM | Stile landen in document.head, nicht im Shadow Root. Kopiere das Style-Tag, dessen Text [data-sonner-toaster] enthält, in den Shadow Root. |
| Toast hinter einem Modal/Overlay oder abgeschnitten | Ein Vorfahre erzeugt einen Stacking-Kontext (transform, filter, overflow) oder das Overlay hat einen höheren z-Index als der Toaster. Verschiebe <Toaster /> an die Dokument-Wurzel, außerhalb jedes Dialog-/Portal-Containers. |
| Dark Mode ignoriert | theme standardmäßig 'light' – setze theme="system" oder übergib das aufgelöste Theme (siehe Theme oben). |
| Erfolg/Fehler sehen grau aus, nicht grün/rot | Das ist der Standard. Füge richColors zum Toaster hinzu. |
| Toast schließt nie | duration: Infinity, dismissible: false oder ein toast.promise, dessen Promise nie erfüllt wird – der Lade-Toast wartet ewig. |
toast.promise bleibt beim Laden hängen | Es benötigt ein Promise (oder eine Funktion, die eines zurückgibt) als erstes Argument, und das Promise muss tatsächlich erfüllt/abgelehnt werden. |
| Wisch-zum-Schließen geht in die falsche Richtung / funktioniert nicht | Die Richtungen leiten sich von position ab. Überschreibe sie mit swipeDirections am Toaster. |
| Toast erscheint in jedem Toaster | Mehrere Toaster müssen anvisiert werden: Gib jedem Toaster eine id und übergib toasterId im toast()-Aufruf. |
| Toasts auf mobilen Geräten zu nah am Bildschirmrand | offset (Desktop, Standard 32px) und mobileOffset (<600px, Standard 16px) – Zahlen, CSS-Strings oder objekte pro Seite. |