Travailler avec Sonner
Réponse initiale
Lorsque ce skill est invoqué pour la première fois sans question spécifique, répondez uniquement par :
Je suis prêt à vous aider à configurer, styliser et résoudre les problèmes avec Sonner, mes connaissances proviennent de son auteur, Emil Kowalski.
Ne fournissez aucune autre information jusqu'à ce que l'utilisateur pose une question.
Un skill guide pour Sonner, la bibliothèque de toasts. Lorsqu'une tâche implique Sonner — le connecter, afficher des toasts, les styliser ou les réparer — répondez d'abord à partir de ce fichier. Les tables de props complètes pour <Toaster /> et toast() se trouvent dans API.md ; lisez-les lorsque vous avez besoin d'un nom de prop, d'un type ou d'une valeur par défaut exacts.
Configuration
Deux éléments, et seulement deux :
- Un seul
<Toaster />, monté une fois, aussi proche de la racine que possible (dans Next.js :layout.tsx— il fonctionne à l'intérieur des composants serveur). Ne le rendez jamais par page ou conditionnellement ; un deuxième Toaster monté duplique chaque toast. toast()appelé depuis du code client — gestionnaires d'événements, effets, callbacks. C'est une simple fonction, pas besoin de hook ou de fournisseur, mais elle ne fait rien côté serveur : dans une action serveur, retournez le résultat et appeleztoast()dans le code client qui le reçoit.
import { Toaster } from 'sonner'; // une fois, dans le layout
import { toast } from 'sonner'; // n'importe où côté client
Choisir le bon appel
| Vous voulez | Appel |
|---|---|
| Un message simple | toast('Titre') — ajoutez { description } pour une deuxième ligne |
| Icône de succès / erreur / info / avertissement | toast.success('…'), toast.error('…'), etc. |
| Spinner pendant que vous gérez vous-même l'état | toast.loading('…'), puis mettez-le à jour par id |
| Chargement → succès/erreur lié à une promesse | toast.promise(promise, { loading, success, error }) — success/error acceptent des fonctions recevant la valeur résolue / l'erreur |
| Bouton qui fait quelque chose | { action: { label, onClick } } — ferme le toast sauf si onClick appelle event.preventDefault() ; cancel est la variante secondaire |
| JSX personnalisé, coque de toast par défaut | toast(<jsx />) |
| JSX personnalisé, sans aucun style | toast.custom((t) => <jsx />) — headless, t vous donne l'id pour fermer |
Recettes
Mettre à jour un toast — appelez toast() à nouveau avec le même id ; seules les props que vous passez changent. Passer à toast.success(…, { id }) change le type. C'est ainsi que fonctionnent les flux chargement → succès sans toast.promise :
const id = toast.loading('Téléchargement…');
toast.success('Téléchargé', { id });
Persister — { duration: Infinity }. Fermer — toast.dismiss(id), ou toast.dismiss() pour tout fermer. Lire les toasts actifs — useSonner() dans React, toast.getActiveToasts() en dehors.
Liens ou composants dans le texte — passez une fonction pour le titre ou la description : toast(() => <a href="…">Voir</a>).
Toasters multiples — donnez à chacun un id et ciblez avec toast('…', { toasterId: 'canvas' }). Sans toasterId, chaque toaster affiche le toast.
Callbacks de fermeture — onDismiss se déclenche sur le bouton de fermeture ou le balayage ; onAutoClose se déclenche lors du délai d'attente. Ils sont séparés ; il n'y a pas de callback unique « fermé ».
Style — l'échelle d'escalade
Ne montez que jusqu'au niveau requis par le changement ; sauter trop tôt à l'échelon supérieur est acceptable (c'est l'état final recommandé), mais rester au milieu ne l'est pas.
- Valeurs par défaut — plus
richColorssur le Toaster pour des succès/erreurs colorés,invertpour inverser par rapport au thème. - Ajustements en ligne —
toastOptions={{ style: {…} }}sur le Toaster pour tous les toasts, oustylepar appeltoast(). - Classes sur les parties —
toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}. Les styles injectés de Sonner gagnent la cascade, donc chaque classe a besoin de!important(Tailwind :!text-red-900). Si vous marquez plus de quelques éléments comme importants, arrêtez — passez au headless. - Headless —
toast.custom()avec votre propre JSX, en conservant le positionnement, l'empilement et le balayage de Sonner. L'approche recommandée pour un toast de système de design : enveloppez-le dans votre propre abstractiontoast(). (unstyled: trueexiste comme solution intermédiaire, mais le headless offre plus de contrôle pour le même effort.)
Icônes — remplacez les valeurs par défaut par type avec la prop icons du Toaster, par toast avec icon, supprimez avec null.
Thème — theme par défaut à 'light' et ne suit pas le système d'exploitation. Passez theme="system", ou connectez votre fournisseur de thème : <Toaster theme={resolvedTheme} /> depuis next-themes.
Résolution des problèmes
| Symptôme | Cause → correctif |
|---|---|
| Le toast n'apparaît jamais | Aucun <Toaster /> monté, ou il a été démonté (render conditionnel, placement par page). Montez-en un à la racine. Si appel depuis une action serveur : toast() est réservé au client — appelez-le avec le résultat de l'action côté client. |
| Le même toast apparaît deux fois | Deux Toasters montés (layout et page) — gardez-en un. Ou toast() déclenché dans un effet sous la double invocation de développement de React StrictMode — déclenchez-le depuis le gestionnaire d'événements à la place, ou passez un id stable pour que le deuxième appel mette à jour plutôt que duplique. |
| Les classes Tailwind/CSS n'ont aucun effet | Les styles par défaut les écrasent. Marquez-les !important, ou utilisez unstyled / headless (voir l'échelle ci-dessus). |
| Les toasts sont rendus complètement sans style (courant dans Astro, transitions de vue) | La feuille de style injectée de Sonner a été perdue — importez-la explicitement dans un layout : import 'sonner/dist/styles.css'. |
| Sans style à l'intérieur du Shadow DOM | Les styles atterrissent dans document.head, pas dans la racine shadow. Copiez la balise style dont le texte inclut [data-sonner-toaster] dans la racine shadow. |
| Toast derrière une modale/overlay, ou rogné | Un ancêtre crée un contexte d'empilement (transform, filter, overflow) ou l'overlay a un z-index supérieur au toaster. Déplacez <Toaster /> à la racine du document, en dehors de tout conteneur de dialogue/portail. |
| Mode sombre ignoré | theme par défaut à 'light' — définissez theme="system" ou passez le thème résolu (voir Thème ci-dessus). |
| Succès/erreur semblent gris, pas vert/rouge | C'est le comportement par défaut. Ajoutez richColors au Toaster. |
| Le toast ne se ferme jamais | duration: Infinity, dismissible: false, ou une toast.promise dont la promesse ne se résout jamais — le toast de chargement attend indéfiniment. |
toast.promise bloqué sur le chargement | Il nécessite une promesse (ou une fonction qui en retourne une) comme premier argument, et la promesse doit réellement se résoudre/rejeter. |
| Le balayage pour fermer va dans la mauvaise direction / ne fonctionne pas | Les directions dérivent de position. Remplacez avec swipeDirections sur le Toaster. |
| Le toast apparaît dans chaque toaster | Les toasters multiples nécessitent un ciblage : donnez un id à chaque Toaster et passez toasterId dans l'appel toast(). |
| Toasts trop proches du bord de l'écran sur mobile | offset (desktop, par défaut 32px) et mobileOffset (<600px, par défaut 16px) — nombres, chaînes CSS, ou objets par côté. |