Toast

Core Idea

Toast exibe mensagens temporárias e não bloqueantes (confirmação, erro, promessa em andamento) fora do fluxo principal da UI, via um manager imperativo (toast.add) em vez de estado React local.

Key Concepts

• toast.add(options): dispara um toast; retorna um id usável para fechar (toast.close(id)) depois.
• type: "success" | "info" | "warning" | "error" | "loading" — renderiza ícone de status automático.
• actionProps: props de botão (children, onClick) passadas para renderizar uma ação dentro do toast (ex. "Undo").
• toast.promise(promise, { loading, success, error }): atualiza um único toast conforme a promise resolve/rejeita.
• <Toaster />: componente que precisa estar montado (geralmente em app/layout.tsx) para os toasts aparecerem.
• priority: "high": eleva prioridade de exibição de um toast (usado em erros).

Code Examples

"use client"

import { Button } from "@/components/ui/button"
import { toast } from "@/components/ui/toast"

export function ToastDemo() {
  function showToast() {
    const id = toast.add({
      title: "Event created",
      description: "Sunday, December 3 at 9:00 AM",
      actionProps: {
        children: "Undo",
        onClick() {
          toast.close(id)
        },
      },
    })
  }

  return (
    <Button variant="outline" onClick={showToast}>
      Show Toast
    </Button>
  )
}

• O que demonstra: disparo imperativo de toast com ação de desfazer usando o id retornado.

toast.promise(
  new Promise<{ name: string }>((resolve) => {
    window.setTimeout(() => resolve({ name: "Event" }), 2000)
  }),
  {
    loading: "Creating event…",
    success: (data) => `${data.name} created.`,
    error: "Could not create event.",
  }
)

• O que demonstra: um único toast que transiciona entre loading/success/error acompanhando uma promise.

Anti-patterns

• Esquecer <Toaster /> no layout: sem ele, toast.add() não renderiza nada visível.
• Gerenciar estado de loading manualmente: prefira toast.promise a criar/fechar toasts à mão para fluxos assíncronos.

Key Takeaways

1. A API é imperativa (toast.add/toast.close), não declarativa como a maioria dos outros componentes shadcn.
2. toast.promise é o padrão certo para operações assíncronas com feedback de progresso.
3. type cuida do ícone; não é necessário compor manualmente com Badge ou ícones extras.
4. Instalação exige @base-ui/react e montar <Toaster /> uma única vez na árvore.

Connects To

• Sonner: página irmã com a mesma API (fonte compartilha o mesmo texto-base de Toast).
• Spinner: usado dentro de badges/botões para estados de loading complementares ao toast.