Trabalhando com Sonner
Resposta Inicial
Quando este skill for invocado pela primeira vez sem uma pergunta específica, responda apenas com:
Estou pronto para ajudar você a configurar, estilizar e solucionar problemas do Sonner. Meu conhecimento vem de seu autor, Emil Kowalski.
Não forneça nenhuma outra informação até que o usuário faça uma pergunta.
Um guia sobre Sonner, a biblioteca de toasts. Quando uma tarefa envolver Sonner — configurá-lo, renderizar toasts, estilizá-los ou corrigi-los — responda a partir deste arquivo primeiro. As tabelas completas de propriedades para <Toaster /> e toast() estão em API.md; leia-as quando precisar de um nome de propriedade, tipo ou valor padrão exato.
Configuração
Duas peças, e apenas duas:
- Um
<Toaster />, montado uma vez, o mais próximo possível da raiz (no Next.js:layout.tsx— funciona dentro de componentes servidor). Nunca o renderize por página ou condicionalmente; um segundo Toaster montado duplica todos os toasts. toast()chamado a partir de código cliente — manipuladores de eventos, efeitos, callbacks. É uma função simples, sem necessidade de hook ou provider, mas não faz nada no servidor: em uma server action, retorne o resultado e chametoast()no código cliente que o recebe.
import { Toaster } from 'sonner'; // uma vez, no layout
import { toast } from 'sonner'; // em qualquer lugar no lado cliente
Escolhendo a chamada correta
| Você quer | Chamada |
|---|---|
| Mensagem simples | toast('Título') — adicione { description } para uma segunda linha |
| Ícone de sucesso / erro / informação / aviso | toast.success('…'), toast.error('…'), etc. |
| Spinner enquanto gerencia o estado manualmente | toast.loading('…'), depois atualize pelo id |
| Loading → sucesso/erro vinculado a uma promise | toast.promise(promise, { loading, success, error }) — success/error aceitam funções que recebem o valor resolvido/erro |
| Botão que faz algo | { action: { label, onClick } } — fecha o toast a menos que onClick chame event.preventDefault(); cancel é a variante secundária |
| JSX personalizado, com invólucro padrão do toast | toast(<jsx />) |
| JSX personalizado, sem estilos | toast.custom((t) => <jsx />) — headless, t fornece o id para descartar |
Receitas
Atualizar um toast — chame toast() novamente com o mesmo id; apenas as props passadas são alteradas. Mudar para toast.success(…, { id }) altera o tipo. É assim que fluxos loading → sucesso funcionam sem toast.promise:
const id = toast.loading('Enviando…');
toast.success('Enviado', { id });
Persistir — { duration: Infinity }. Descartar — toast.dismiss(id), ou toast.dismiss() para todos. Ler toasts ativos — useSonner() no React, toast.getActiveToasts() fora dele.
Links ou componentes no texto — passe uma função para o título ou descrição: toast(() => <a href="…">Ver</a>).
Múltiplos toasters — dê a cada um um id e direcione com toast('…', { toasterId: 'canvas' }). Sem toasterId, todos os toasters renderizam o toast.
Callbacks de fechamento — onDismiss é acionado pelo botão de fechar ou swipe; onAutoClose é acionado no timeout. Eles são separados; não existe um callback único "fechado".
Estilização — a escada de escalada
Suba apenas até onde a mudança exige; pular para o degrau mais alto cedo demais é aceitável (é o estado final recomendado), mas permanecer no meio não é.
- Padrões — mais
richColorsno Toaster para sucesso/erro coloridos,invertpara inverter contra o tema. - Ajustes inline —
toastOptions={{ style: {…} }}no Toaster para todos os toasts, oustylepor chamadatoast(). - Classes em partes —
toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}. Os estilos injetados do Sonner vencem a cascata, então toda classe precisa de!important(Tailwind:!text-red-900). Se você estiver marcando mais do que algumas coisas como important, pare — vá para headless. - Headless —
toast.custom()com seu próprio JSX, mantendo o posicionamento, empilhamento e swipe do Sonner. A abordagem recomendada para um toast de sistema de design: envolva-o em sua própria abstraçãotoast(). (unstyled: trueexiste como meio-termo, mas headless oferece mais controle pelo mesmo esforço.)
Ícones — substitua os padrões por tipo com a prop icons do Toaster, por toast com icon, remova com null.
Tema — theme padrão é 'light' e não acompanha o SO. Passe theme="system", ou conecte seu provedor de tema: <Toaster theme={resolvedTheme} /> do next-themes.
Solução de Problemas
| Sintoma | Causa → correção |
|---|---|
| O toast nunca aparece | Nenhum <Toaster /> montado, ou foi desmontado (renderização condicional, posicionamento por página). Monte um na raiz. Se estiver chamando de uma server action: toast() é apenas cliente — chame-o com o resultado da ação no cliente. |
| O mesmo toast aparece duas vezes | Dois Toasters montados (layout e página) — mantenha um. Ou toast() disparado em um efeito sob a dupla invocação de desenvolvimento do React StrictMode — dispare do manipulador de evento em vez disso, ou passe um id estável para que a segunda chamada atualize em vez de duplicar. |
| Classes Tailwind/CSS não têm efeito | Os estilos padrão as sobrescrevem. Marque-as com !important, ou use unstyled / headless (veja a escada acima). |
| Toasts renderizam completamente sem estilo (comum no Astro, transições de visualização) | A folha de estilo injetada do Sonner foi perdida — importe-a explicitamente em um layout: import 'sonner/dist/styles.css'. |
| Sem estilo dentro de Shadow DOM | Os estilos vão parar em document.head, não na raiz da sombra. Copie a tag style cujo texto inclui [data-sonner-toaster] para dentro da raiz da sombra. |
| Toast atrás de um modal/overlay, ou cortado | Um ancestral cria um contexto de empilhamento (transform, filter, overflow) ou o overlay tem z-index maior que o toaster. Mova <Toaster /> para a raiz do documento, fora de qualquer contêiner de diálogo/portal. |
| Modo escuro ignorado | theme padrão é 'light' — defina theme="system" ou passe o tema resolvido (veja Tema acima). |
| Sucesso/erro parecem cinza, não verde/vermelho | Isso é o padrão. Adicione richColors ao Toaster. |
| O toast nunca fecha | duration: Infinity, dismissible: false, ou uma toast.promise cuja promise nunca é resolvida — o toast de loading espera para sempre. |
toast.promise preso no loading | Ele precisa de uma promise (ou uma função que retorne uma) como primeiro argumento, e a promise deve realmente resolver/rejeitar. |
| Swipe-para-descartar vai na direção errada / não funciona | As direções derivam de position. Substitua com swipeDirections no Toaster. |
| O toast aparece em todos os toasters | Múltiplos toasters precisam de direcionamento: dê a cada Toaster um id e passe toasterId na chamada toast(). |
| Toasts muito próximos da borda da tela no celular | offset (desktop, padrão 32px) e mobileOffset (<600px, padrão 16px) — números, strings CSS ou objetos por lado. |