Toast

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

// <Toaster /> is mounted once in the root layout — see Usage.
export default function ToastDemo() {
  return (
    <Button
      variant="outline"
      onPress={() =>
        toast("Event created", {
          description: "Design review · Friday, June 14 at 10:00 AM",
          action: { label: "Undo", onClick: () => toast("Event removed") },
        })
      }
    >
      Show toast
    </Button>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/toast

The CLI installs dependencies and any other components this one uses.

Toasts only appear where a <Toaster /> is mounted, and every mounted <Toaster /> without an id renders every toast, so two of them show duplicates. Mount it once in the root layout, not inside pages or dialogs.

When to use

Toast — short feedback about something that just happened ("Saved", "Invite sent", "Deploy failed"), or background work the user doesn't have to wait on.
Alert — a message that belongs to the page and must stay visible until the situation changes, such as a form error or a billing problem.
Dialog — when the user must respond before continuing.
Don't put the only way to do something in a toast; it disappears. Actions like "Undo" should be shortcuts for something also reachable elsewhere.

Anatomy

tsx

<Toaster />                      {/* <section aria-live="polite"> › <ol> per position */}

toast(title, {
  icon,                          // leading icon (typed toasts get one by default)
  description,                   // secondary line
  action,                        // primary button
  cancel,                        // secondary button
});

Part	Renders	Notes
`Toaster`	`<section>` › `<ol>`	The live region and one list per position in use. Themed with popover tokens.
Toast	`<li data-sonner-toast>`	One notification. Carries `data-type` (`success`, `error`, …).
Icon	`<div data-icon>`	Lucide icon per type; tinted with the matching status color.
Title	`<div data-title>`	The first argument to `toast()`.
Description	`<div data-description>`	Muted secondary text.
Action / Cancel	`<button>`	From `action` and `cancel`. The action closes the toast unless its `onClick` calls `event.preventDefault()`; cancel always closes it.
Close button	`<button aria-label="Close toast">`	Shown when `closeButton` is set on the toast or the Toaster. Never shown on loading or custom toasts.

Examples

Types

toast() shows a plain message. toast.success, toast.info, toast.warning and toast.error add a tinted icon that matches the status colors of the rest of the library.

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

export default function ToastTypes() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button variant="outline" onPress={() => toast("Draft saved")}>
        Default
      </Button>
      <Button variant="outline" onPress={() => toast.success("Changes saved")}>
        Success
      </Button>
      <Button
        variant="outline"
        onPress={() => toast.info("A new version is available")}
      >
        Info
      </Button>
      <Button
        variant="outline"
        onPress={() => toast.warning("You're using 92% of your storage")}
      >
        Warning
      </Button>
      <Button variant="outline" onPress={() => toast.error("Payment failed")}>
        Error
      </Button>
    </div>
  );
}

Description

description adds a muted second line for detail that doesn't fit the title. Keep the title short enough to scan.

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

export default function ToastDescription() {
  return (
    <Button
      variant="outline"
      onPress={() =>
        toast.success("Invitation sent", {
          description: "maya@acme.com will get an email to join Acme Inc.",
        })
      }
    >
      Invite teammate
    </Button>
  );
}

Actions

action renders a primary button, cancel a secondary one. Both take a label and an onClick, and close the toast after running. Use them for quick follow-ups like "Undo" or "View".

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

export default function ToastAction() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onPress={() =>
          toast("Conversation archived", {
            action: {
              label: "Undo",
              onClick: () => toast.success("Conversation restored"),
            },
          })
        }
      >
        Action
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast("Update available", {
            description: "Restart to install version 2.4.0.",
            action: {
              label: "Restart",
              onClick: () => toast.info("Restarting…"),
            },
            cancel: { label: "Later", onClick: () => {} },
          })
        }
      >
        Action and cancel
      </Button>
    </div>
  );
}

Promise

toast.promise shows a loading toast, then replaces it with the result. success and error can be functions that receive the resolved value or the rejection reason.

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

function deploy(shouldFail: boolean) {
  return new Promise<{ url: string }>((resolve, reject) =>
    setTimeout(
      () =>
        shouldFail
          ? reject(new Error("Build exited with code 1"))
          : resolve({ url: "acme-web.vercel.app" }),
      2000,
    ),
  );
}

export default function ToastPromise() {
  const run = (shouldFail: boolean) =>
    toast.promise(deploy(shouldFail), {
      loading: "Deploying acme-web…",
      success: (data) => `Deployed to ${data.url}`,
      error: (err: Error) => `Deploy failed: ${err.message}`,
    });

  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button variant="outline" onPress={() => run(false)}>
        Deploy
      </Button>
      <Button variant="outline" onPress={() => run(true)}>
        Deploy (fails)
      </Button>
    </div>
  );
}

Updating a toast

Every call returns an id. Pass it back as id to update the same toast in place — for example, to walk a toast.loading toast through several steps before it succeeds.

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

export default function ToastUpdate() {
  async function sync() {
    const id = toast.loading("Syncing contacts…");
    await new Promise((r) => setTimeout(r, 1200));
    toast.loading("Merging duplicates…", { id });
    await new Promise((r) => setTimeout(r, 1200));
    toast.success("Contacts synced", {
      id,
      description: "342 contacts imported, 12 duplicates merged.",
    });
  }

  return (
    <Button variant="outline" onPress={sync}>
      Sync contacts
    </Button>
  );
}

Dismissing

toast.dismiss(id) closes one toast; toast.dismiss() closes them all. Use it for toasts that track a state the user can end elsewhere.

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

export default function ToastDismiss() {
  const lastId = useRef<string | number | null>(null);

  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onPress={() => {
          lastId.current = toast("Recording started", {
            duration: Number.POSITIVE_INFINITY,
          });
        }}
      >
        Start recording
      </Button>
      <Button
        variant="outline"
        onPress={() => {
          if (lastId.current !== null) toast.dismiss(lastId.current);
        }}
      >
        Dismiss last
      </Button>
      <Button variant="ghost" onPress={() => toast.dismiss()}>
        Dismiss all
      </Button>
    </div>
  );
}

Duration and close button

Toasts close after 4 seconds by default. Shorten duration for trivial confirmations, lengthen it for anything with text to read, and use Infinity with closeButton for ongoing states. Timers pause while the user hovers the stack or the tab is hidden.

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

export default function ToastDuration() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onPress={() => toast("Link copied", { duration: 1500 })}
      >
        Short (1.5s)
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast.warning("Your session expires in 5 minutes", {
            duration: 10000,
            closeButton: true,
          })
        }
      >
        Long with close button
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast.error("Connection lost", {
            description: "Reconnecting… Changes are saved locally.",
            duration: Number.POSITIVE_INFINITY,
            closeButton: true,
          })
        }
      >
        Until dismissed
      </Button>
    </div>
  );
}

Custom icon

icon replaces the default icon, and adds one to plain toasts. Size it with size-4 to match the built-in icons.

import { CalendarCheckIcon, MailIcon, StarIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { toast } from "@/components/ui/toast";

export default function ToastIcon() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onPress={() =>
          toast("Starred “Q3 planning”", {
            icon: <StarIcon className="size-4 fill-warning text-warning" />,
          })
        }
      >
        Star
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast("3 new messages", { icon: <MailIcon className="size-4" /> })
        }
      >
        Messages
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast.success("Meeting booked", {
            icon: <CalendarCheckIcon className="size-4" />,
          })
        }
      >
        Booking
      </Button>
    </div>
  );
}

Rich colors

richColors: true tints the whole toast with sonner's success, info, warning and error palettes. Set it on the <Toaster /> to apply it to every toast. The palettes switch to their dark variants automatically when your app is in dark mode (see Color mode); toggle the docs theme to compare.

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

export default function ToastRichColors() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onPress={() => toast.success("Payment received", { richColors: true })}
      >
        Success
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast.warning("Card expires this month", { richColors: true })
        }
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onPress={() =>
          toast.error("Couldn't charge card ending 4242", {
            richColors: true,
          })
        }
      >
        Error
      </Button>
    </div>
  );
}

Position

The Toaster's position (default bottom-right) sets where toasts appear. Individual toasts can override it with their own position.

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

const positions = [
  "top-left",
  "top-center",
  "top-right",
  "bottom-left",
  "bottom-center",
  "bottom-right",
] as const;

export default function ToastPosition() {
  return (
    <div className="grid w-full max-w-md grid-cols-3 gap-2">
      {positions.map((position) => (
        <Button
          key={position}
          variant="outline"
          size="sm"
          onPress={() => toast(`Shown ${position}`, { position })}
        >
          {position}
        </Button>
      ))}
    </div>
  );
}

Custom content

toast.custom renders your own JSX and keeps sonner's stacking, timing and swipe-to-dismiss. The render function receives the toast's id so buttons inside can dismiss it.

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

export default function ToastCustom() {
  return (
    <Button
      variant="outline"
      onPress={() =>
        toast.custom(
          (id) => (
            <div className="flex w-(--width) gap-3 rounded-lg bg-popover p-4 text-popover-foreground text-sm">
              <Avatar alt="Maya Chen" fallback="MC" colorful />
              <div className="flex min-w-0 flex-1 flex-col gap-2">
                <p>
                  <span className="font-medium">Maya Chen</span> mentioned you
                  in <span className="font-medium">Q3 roadmap</span>
                </p>
                <p className="line-clamp-2 text-muted-foreground">
                  “Can you take a look at the pricing section before Friday?”
                </p>
                <div className="flex gap-2">
                  <Button size="xs" onPress={() => toast.dismiss(id)}>
                    Reply
                  </Button>
                  <Button
                    size="xs"
                    variant="ghost"
                    onPress={() => toast.dismiss(id)}
                  >
                    Dismiss
                  </Button>
                </div>
              </div>
            </div>
          ),
          { duration: 8000 },
        )
      }
    >
      Show notification
    </Button>
  );
}

Recipes

Save with toast.promise

Submit a form, keep the button pending until the promise settles, and let toast.promise report success or the server's error message. finally resets the button either way.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { TextField } from "@/components/ui/text-field";
import { toast } from "@/components/ui/toast";

function saveProfile(data: FormData) {
  return new Promise<string>((resolve, reject) =>
    setTimeout(() => {
      const handle = String(data.get("handle"));
      if (handle === "admin") reject(new Error("That handle is reserved."));
      else resolve(handle);
    }, 1200),
  );
}

export default function ToastRecipeSaveForm() {
  const [pending, setPending] = useState(false);

  return (
    <Form
      className="grid w-full max-w-sm gap-4 rounded-xl border bg-card p-5"
      onSubmit={async (e) => {
        e.preventDefault();
        setPending(true);
        const save = saveProfile(new FormData(e.currentTarget));
        toast.promise(save, {
          loading: "Saving profile…",
          success: (handle) => ({
            message: "Profile updated",
            description: `Your public URL is acme.com/@${handle}`,
          }),
          error: (err: Error) => ({
            message: "Couldn't save profile",
            description: err.message,
          }),
          finally: () => setPending(false),
        });
      }}
    >
      <TextField label="Display name" name="name" defaultValue="Maya Chen" />
      <TextField
        label="Handle"
        name="handle"
        defaultValue="maya"
        description="Try “admin” to see the error state."
        isRequired
      />
      <Button type="submit" isPending={pending} className="justify-self-end">
        Save
      </Button>
    </Form>
  );
}

Delete with undo

Remove the item from the list right away and offer "Undo" in the toast. Commit the delete in onAutoClose, once the undo window has passed.

Launch plan.md
Edited 2 hours ago
Pricing research.md
Edited Yesterday
Interview notes.md
Edited May 28
Retro — sprint 42.md
Edited May 21

import { FileTextIcon, Trash2Icon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { toast } from "@/components/ui/toast";

const initial = [
  { id: "1", name: "Launch plan.md", edited: "2 hours ago" },
  { id: "2", name: "Pricing research.md", edited: "Yesterday" },
  { id: "3", name: "Interview notes.md", edited: "May 28" },
  { id: "4", name: "Retro — sprint 42.md", edited: "May 21" },
];

export default function ToastRecipeUndoDelete() {
  const [docs, setDocs] = useState(initial);

  function remove(doc: (typeof initial)[number]) {
    const index = docs.findIndex((d) => d.id === doc.id);
    setDocs((list) => list.filter((d) => d.id !== doc.id));
    toast(`Deleted “${doc.name}”`, {
      action: {
        label: "Undo",
        onClick: () =>
          setDocs((list) => {
            const next = [...list];
            next.splice(index, 0, doc);
            return next;
          }),
      },
      // Commit the delete on the server only once the undo window has passed.
      onAutoClose: () => console.log(`DELETE /docs/${doc.id}`),
    });
  }

  return (
    <div className="w-full max-w-sm rounded-xl border bg-card">
      {docs.length === 0 ? (
        <div className="flex flex-col items-center gap-2 p-6 text-center">
          <p className="text-muted-foreground text-sm">No documents</p>
          <Button size="sm" variant="outline" onPress={() => setDocs(initial)}>
            Reset
          </Button>
        </div>
      ) : (
        <ul className="divide-y">
          {docs.map((doc) => (
            <li key={doc.id} className="flex items-center gap-3 px-4 py-2.5">
              <FileTextIcon className="size-4 shrink-0 text-muted-foreground" />
              <div className="min-w-0 flex-1">
                <p className="truncate font-medium text-sm">{doc.name}</p>
                <p className="text-muted-foreground text-xs">
                  Edited {doc.edited}
                </p>
              </div>
              <Button
                size="icon-sm"
                variant="ghost"
                aria-label={`Delete ${doc.name}`}
                onPress={() => remove(doc)}
              >
                <Trash2Icon />
              </Button>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Export progress

A custom toast with a ProgressBar, re-rendered through the same id as the export runs, then swapped for a success toast with a download action.

import { DownloadIcon, FileArchiveIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { ProgressBar } from "@/components/ui/progress-bar";
import { toast } from "@/components/ui/toast";

function ExportToast({ value }: { value: number }) {
  return (
    <div className="flex w-(--width) gap-3 rounded-lg bg-popover p-4 text-popover-foreground">
      <FileArchiveIcon className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
      <div className="flex min-w-0 flex-1 flex-col gap-2">
        <p className="font-medium text-sm">Exporting workspace</p>
        <ProgressBar
          aria-label="Export progress"
          value={value}
          size="sm"
          showValue={false}
        />
        <p className="text-muted-foreground text-xs tabular-nums">
          {Math.round(value)}% · workspace-export.zip
        </p>
      </div>
    </div>
  );
}

export default function ToastRecipeExportProgress() {
  async function start() {
    const id = toast.custom(() => <ExportToast value={0} />, {
      duration: Number.POSITIVE_INFINITY,
    });
    for (let value = 10; value <= 100; value += 10) {
      await new Promise((r) => setTimeout(r, 350));
      toast.custom(() => <ExportToast value={value} />, {
        id,
        duration: Number.POSITIVE_INFINITY,
      });
    }
    // A custom toast can't turn back into a standard one, so swap it out.
    toast.dismiss(id);
    toast.success("Export ready", {
      description: "workspace-export.zip · 184 MB",
      duration: 6000,
      action: { label: "Download", onClick: () => {} },
    });
  }

  return (
    <Button variant="outline" onPress={start}>
      <DownloadIcon /> Export workspace
    </Button>
  );
}

Accessibility

The Toaster renders a <section> with aria-live="polite", so new toasts are announced without interrupting and without moving focus.
The region is labelled "Notifications" plus the hotkey. Press Alt+T to expand the stack and move focus into it; each toast is focusable.
Timers pause while the stack is expanded (hovered, or opened with the hotkey), while a toast is being pressed or swiped, and while the page is hidden.
sonner disables its own transitions and animations under prefers-reduced-motion, and the Lucide loading icon stops spinning (motion-reduce:animate-none).
Toasts disappear. Keep messages short, give important ones a longer duration, and never make a toast the only way to reach an action.
For errors that block the user, prefer an Alert near the cause, or pair the toast with one.

Keyboard

Key	Action
`Alt`+`T`	Expands the toasts and moves focus to them (configurable with `hotkey`)
`Tab` / `Shift`+`Tab`	Moves between toasts and their buttons
`Enter` / `Space`	Activates the focused action, cancel or close button
`Esc`	Collapses the expanded stack when focus is inside it

Styling

Theme

Toaster maps sonner's colors to your tokens: --normal-bg is --popover, --normal-text is --popover-foreground, --normal-border is --border and --border-radius is --radius. It also sets toastOptions.classNames for the toast shadow, muted descriptions, primary action buttons, muted cancel buttons and per-type icon colors, and replaces the icons with Lucide ones.

Your props are merged with these defaults instead of replacing them:

Prop	How it merges
`className`	Joined with the built-in `toaster group` classes (tailwind-merge).
`style`	Shallow-merged over the token variables, so you can override one, such as `--width`, and keep the rest.
`icons`	Merged per type. Passing only `success` keeps the Lucide info, warning, error and loading icons.
`toastOptions`	Every option is passed through; `toastOptions.classNames` is merged key by key with `cn`, so your `toast` or `actionButton` classes are added to the defaults.

tsx

<Toaster
  icons={{ success: <PartyPopperIcon className="size-4" /> }}
  toastOptions={{ classNames: { title: "!font-semibold" } }}
  style={{ "--width": "420px" } as React.CSSProperties}
/>

sonner's own styles aren't in a cascade layer, so the defaults use the ! (important) modifier. Use ! on your classes too when they need to beat a sonner style or a default, for example !bg-card.

Color mode

sonner's richColors and invert palettes depend on its theme. By default Toaster follows the .dark class on <html>, the same switch the theme tokens use, and watches it with a MutationObserver, so toasts change palette the moment your theme toggle runs. This works with next-themes (attribute="class"), fumadocs and hand-rolled toggles alike, and adds no dependency. During server rendering and hydration it uses "light", then switches after hydration.

Pass theme to take over: "light" or "dark" to pin it, or "system" to follow prefers-color-scheme instead of the class (useful if your app themes with media queries rather than .dark).

Custom toasts

toast.custom content still receives the toast classes (border, radius and shadow) on its <li>, but no background, padding or width. Give your root element bg-popover, padding and w-(--width) (356px by default).

Per-toast classes

Every toast accepts className, classNames (with keys such as title, description, actionButton, icon) and style, merged with the Toaster's defaults.

API Reference

Toaster

Prop

Type

toast()

tsx

toast(message, options?)          // plain
toast.success(message, options?)  // .info, .warning, .error, .loading, .message
toast.promise(promise, { loading, success, error, description?, finally? })
toast.custom((id) => <JSX />, options?)
toast.dismiss(id?)                // one toast, or all of them

Every call except dismiss returns the toast's id. toast.promise returns an object with unwrap(), which resolves or rejects with the original promise.

Prop

Type

toast.promise

Prop

Type

Also accepts every toast() option except description, which takes the form above. See the sonner docs for the full reference.

Alert — persistent, in-page messages.
Dialog — when the user must respond.
Progress Bar — progress inside a custom toast.
Button — isPending for the action that triggers the toast.