Toasts

Toasts are transient notifications for system feedback: saves, approvals, exports, validations, and background operations. This implementation is token-driven, theme-safe, keyboard-friendly, and supports actions, persistence, and loading-to-success updates.

Notes: Toasts render in a fixed viewport via portal, so placement is independent of any docs preview cards and won’t be clipped by layouts.

Install Provider

Place ToastProvider near the app root so any feature can push notifications.

ToastProvider is mounted for this docs page. Use the sections below to trigger toasts.

Show code

import { ToastProvider } from "@/design-system/components/Toast";

export default function RootLayout({ children }) {
  return (
    <ToastProvider placement="bottom-end" maxToasts={4} defaultDuration={4500}>
      {children}
    </ToastProvider>
  );
}

Placements

All enterprise placements supported (top/middle/bottom × start/center/end).

Current placement: bottom-end

Show code

import { ToastProvider, TOAST_PLACEMENTS } from "@/design-system/components/Toast";

const placements = TOAST_PLACEMENTS;
// "top-start" | "top-center" | "top-end"
// "middle-start" | "middle-center" | "middle-end"
// "bottom-start" | "bottom-center" | "bottom-end"

export function Example() {
  return <ToastProvider placement="top-center">{/* ... */}</ToastProvider>;
}

Default Toast

Enterprise default: surface variant, tone-driven icon, close button, and optional progress.

Show code

import { Button } from "@/design-system/components/Button";
import { useToast } from "@/design-system/components/Toast";

export function Example() {
  const { push } = useToast();

  return (
    <Button
      variant="primary"
      onClick={() =>
        push({
          tone: "success",
          title: "Saved",
          message: "Student record updated successfully.",
          showProgress: true,
        })
      }
    >
      Show toast
    </Button>
  );
}

Tones

Success, warning, and danger are the core semantic tones used across Aggarly Platform.

Show code

push({
  tone: "danger",
  title: "Sync failed",
  message: "We couldn’t sync changes. Check connection and retry.",
  duration: 0, // persistent
  actions: [{ label: "Retry", onClick: () => {/* retry */} }],
});

Variants

Surface (default), soft, outline, solid, and glass (premium, less transparent).

Show code

push({ tone: "success", variant: "soft", title: "Soft", message: "Subtle tint.", showProgress: true });

Actions

Action toasts for Undo/Retry/Download. Keep actions short and high-signal.

Show code

push({
  tone: "neutral",
  title: "Student archived",
  message: "You can restore this student for the next 10 minutes.",
  actions: [{ label: "Undo", onClick: () => {/* restore */} }],
  showProgress: true,
});

Sizing and Loading

Small toasts for dense workflows. Loading toasts can update into success states.

Show code

const id = push({
  id: "upload", // reusing id will update the existing toast (dedupe)
  tone: "primary",
  variant: "soft",
  title: "Uploading…",
  message: "Securely transferring files to the server.",
  duration: 0,
  loading: true,
  dismissible: false,
});

setTimeout(() => {
  update(id, {
    tone: "success",
    variant: "surface",
    title: "Upload complete",
    message: "Files are available in the student record.",
    duration: 3800,
    dismissible: true,
    loading: false,
    showProgress: true,
  });
}, 1200);

Toasts

Notes: Toasts render in a fixed viewport via portal, so placement is independent of any docs preview cards and won’t be clipped by layouts.

import { ToastProvider } from "@/design-system/components/Toast"; export default function RootLayout({ children }) { return ( <ToastProvider placement="bottom-end" maxToasts={4} defaultDuration={4500}> {children} </ToastProvider> ); }

import { ToastProvider, TOAST_PLACEMENTS } from "@/design-system/components/Toast"; const placements = TOAST_PLACEMENTS; // "top-start" | "top-center" | "top-end" // "middle-start" | "middle-center" | "middle-end" // "bottom-start" | "bottom-center" | "bottom-end" export function Example() { return <ToastProvider placement="top-center">{/* ... */}</ToastProvider>; }

import { Button } from "@/design-system/components/Button"; import { useToast } from "@/design-system/components/Toast"; export function Example() { const { push } = useToast(); return ( <Button variant="primary" onClick={() => push({ tone: "success", title: "Saved", message: "Student record updated successfully.", showProgress: true, }) } > Show toast </Button> ); }

push({ tone: "danger", title: "Sync failed", message: "We couldn’t sync changes. Check connection and retry.", duration: 0, // persistent actions: [{ label: "Retry", onClick: () => {/* retry */} }], });

push({ tone: "neutral", title: "Student archived", message: "You can restore this student for the next 10 minutes.", actions: [{ label: "Undo", onClick: () => {/* restore */} }], showProgress: true, });

const id = push({ id: "upload", // reusing id will update the existing toast (dedupe) tone: "primary", variant: "soft", title: "Uploading…", message: "Securely transferring files to the server.", duration: 0, loading: true, dismissible: false, }); setTimeout(() => { update(id, { tone: "success", variant: "surface", title: "Upload complete", message: "Files are available in the student record.", duration: 3800, dismissible: true, loading: false, showProgress: true, }); }, 1200);