72Começar
HextaUI

Toast

Mensagens breves que se empilham com ordem, expandem no hover, saem com deslize e transformam um estado de carregamento em sucesso ou erro no próprio lugar.

"use client"

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

export function ToastDemo() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast("Event created", {
          description: "Sunday, December 3 at 9:00 AM",
          action: { label: "Undo", onClick: () => toast("Event removed") },
        })
      }
    >
      Show toast
    </Button>
  )
}

Instalação

pnpm dlx shadcn@latest add https://hextaui.com/r/toast.json

Adiciona o componente, os tokens de tema do HextaUI e quaisquer componentes do HextaUI dos quais ele depende.

Uso

Adicione <Toaster /> uma vez, perto da raiz do seu app.

import { Toaster } from "@/components/ui/toast"

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  )
}

Depois chame toast de qualquer lugar, inclusive fora de componentes React.

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

toast("Event created", { description: "Sunday at 9:00 AM" })
toast.success("Payment received")
toast.promise(save(), { loading: "Saving…", success: "Saved", error: "Couldn't save" })

Os toasts se empilham numa pilha organizada, com o mais novo na frente. Passe o mouse ou foque a pilha para abri-la em leque; todos os temporizadores pausam enquanto você lê. Deslize um toast em direção à borda para dispensá-lo.

Exemplos

Tipos

Todo toast usa a mesma superfície calma; apenas o ícone leva a cor.

"use client"

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

export function ToastTypes() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button variant="outline" size="sm" onClick={() => toast("Draft saved")}>
        Default
      </Button>
      <Button
        variant="outline"
        size="sm"
        onClick={() => toast.success("Payment received")}
      >
        Success
      </Button>
      <Button
        variant="outline"
        size="sm"
        onClick={() =>
          toast.error("Couldn't upload photo", {
            description: "The file is larger than 10 MB.",
          })
        }
      >
        Error
      </Button>
      <Button
        variant="outline"
        size="sm"
        onClick={() => toast.warning("Storage almost full")}
      >
        Warning
      </Button>
      <Button
        variant="outline"
        size="sm"
        onClick={() => toast.info("A new version is available")}
      >
        Info
      </Button>
    </div>
  )
}

Promise

toast.promise mostra um spinner e depois se transforma em um toast de sucesso ou erro no mesmo lugar, com o ícone surgindo ao mudar.

"use client"

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

let attempt = 0

function deploy() {
  attempt += 1
  const fails = attempt % 2 === 0
  return new Promise<{ url: string }>((resolve, reject) =>
    setTimeout(
      () =>
        fails
          ? reject(new Error("Build failed"))
          : resolve({ url: "hextaui.com" }),
      1800
    )
  )
}

export function ToastPromise() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast.promise(deploy(), {
          loading: "Deploying…",
          success: (data) => ({
            title: "Deployed",
            description: `Live at ${data.url}`,
          }),
          error: (error) => ({
            title: "Deploy failed",
            description: error instanceof Error ? error.message : "Try again.",
          }),
        })
      }
    >
      Deploy (fails every other time)
    </Button>
  )
}

Ação

Passe action para um botão como Undo. Clicar nele também dispensa o toast.

"use client"

import * as React from "react"

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

export function ToastAction() {
  const [archived, setArchived] = React.useState(0)

  return (
    <div className="flex flex-col items-center gap-3">
      <Button
        variant="outline"
        onClick={() => {
          setArchived((count) => count + 1)
          toast("Conversation archived", {
            action: {
              label: "Undo",
              onClick: () => setArchived((count) => count - 1),
            },
          })
        }}
      >
        Archive
      </Button>
      <p className="text-sm text-muted-foreground tabular-nums">
        {archived} archived
      </p>
    </div>
  )
}

Atualizar no lugar

Guarde o id de toast.loading e altere-o com toast.update, inclusive o tipo.

"use client"

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

export function ToastUpdate() {
  return (
    <Button
      variant="outline"
      onClick={() => {
        const id = toast.loading("Uploading 3 files…")
        setTimeout(() => toast.update(id, { title: "Uploading 2 of 3…" }), 900)
        setTimeout(
          () =>
            toast.update(id, {
              type: "success",
              title: "Upload complete",
              description: "3 files added to Photos.",
            }),
          1800
        )
      }}
    >
      Upload files
    </Button>
  )
}

Sem duplicatas

Dê um id a um toast e chamá-lo de novo atualiza o existente em vez de empilhar uma cópia.

"use client"

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

export function ToastDedupe() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast.info("You're offline", {
          id: "offline",
          description: "Changes will sync when you reconnect.",
        })
      }
    >
      Go offline (click twice)
    </Button>
  )
}

Teclado

TeclaAção
F6Move o foco para os toasts e os abre em leque.
TabMove entre as ações dos toasts e os botões de fechar.
EscDispensa o toast com foco.

Acessibilidade

  • Os toasts são anunciados de forma educada; toast.error é anunciado imediatamente.
  • Os temporizadores pausam enquanto o ponteiro ou o foco está nos toasts, então ninguém precisa correr contra uma contagem regressiva.
  • Os botões de fechar aparecem no hover e no foco, e ficam sempre visíveis em telas touch.
  • Com movimento reduzido, os toasts aparecem com fade em vez de deslizar.

Referência da API

Toaster

PropTipoPadrão
positionCelulares sempre usam a largura total.
"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right""bottom-right"
limitToasts exibidos ao mesmo tempo; os mais antigos desaparecem.
number3
timeoutTempo padrão na tela, em ms.
number5000
AtributoDescrição
data-slot="toaster"O viewport, com data-position.
data-slot="toast"Cada toast, com data-type, data-expanded e data-swiping.

toast()

PropTipoPadrão
description
ReactNode–
action
{ label: ReactNode; onClick?: (event) => void }–
idReutilize para atualizar em vez de duplicar.
string–
timeoutO padrão é o timeout do Toaster. Mensagens longas ficam mais tempo, cerca de 250 palavras por minuto.
number–
priority
"low" | "high""low"
onClose
() => void–
onRemove
() => void–

Também toast.success, toast.error, toast.warning, toast.info, toast.loading, toast.promise, toast.update e toast.dismiss. Cada um retorna ou recebe o id do toast.

Relacionados

Usado em blocos

Blocos que se baseiam em Toast.