Toast

Temporary success feedback and other brief, dismissible status messages after a real user action.

Purpose

Use Toast for brief feedback after a real user action when the message does not require a blocking decision.

Action feedback

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

export function Example() {
  return (
    <Button onClick={() => toastManager.add({ title: "Saved", type: "success" })}>
      Show toast
    </Button>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/toast

Import

import { ToastProvider, toastManager } from "@/components/ui/toast";

Need the machine-readable source metadata? View registry JSON.

Usage

Toast is for transient feedback after an action. Add it through toastManager and keep ToastProvider at the app root.

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

export function Example() {
  return (
    <Button onClick={() => toastManager.add({ title: "Saved", type: "success" })}>
      Show toast
    </Button>
  );
}

Examples

Semantic types, an action button and per-toast timeouts are options of toastManager.add. ToastProvider mounts once at the app root; its position prop (default bottom-right) applies to every toast.

Types

Untyped toasts render without an icon. Loading toasts stay until they are updated or dismissed; this demo resolves to success after two seconds.

{/* Untyped: no icon */}
toastManager.add({ title: "Event has been created" });

{/* Semantic types render a matching icon */}
toastManager.add({ title: "Success!", type: "success" });
toastManager.add({ title: "Uh oh! Something went wrong.", type: "error" });
toastManager.add({ title: "Heads up!", type: "info" });
toastManager.add({ title: "Warning!", type: "warning" });

{/* Loading toasts never auto-dismiss; update them when done */}
const id = toastManager.add({ title: "Uploading report", type: "loading" });
toastManager.update(id, { title: "Upload complete", type: "success" });

With action

toastManager.add({
  title: "Message archived",
  description: "The conversation moved to the archive.",
  actionProps: {
    children: "Undo",
    onClick: () => toastManager.add({ title: "Message restored", type: "success" }),
  },
});

Custom duration

{/* Dismisses after 1.2 seconds */}
toastManager.add({ title: "Copied to clipboard", timeout: 1200 });

{/* Stays for 8 seconds */}
toastManager.add({ title: "Export ready", type: "success", timeout: 8000 });

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Mount one ToastProvider at the app root. Its position supports top-left, top-center, top-right, bottom-left, bottom-center and bottom-right.
Use toastManager.add, toastManager.update, toastManager.close and toastManager.promise(promise, { loading, success, error }) from anywhere below the provider.
Position controls viewport corner, stack direction, entry and exit direction, and the permitted swipe direction.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Toast stacking, height, opacity, transform and swipe exit use the central Siteplane motion tokens.
The forced reducedMotionPreset shortens the tokenized stack transitions. Provider and operating-system reduced-motion modes stop both the continuous loading-icon spin and the cosmetic success/error update replay; messages and dismissal remain functional.

Accessibility

Keep messages concise and announce the result of a real action; do not hide critical instructions only in a transient Toast.
Every Toast remains manually dismissible in addition to its timeout.
Choose wording and urgency that match the result, and avoid firing repeated messages for routine state changes.

Implementation Guidance

Mount exactly one app-wide provider and set its position deliberately.
Use toastManager.promise for a promise lifecycle instead of manually recreating loading, success and error updates.
Use Alert, inline validation or Dialog for information that must remain visible or requires a decision.