Back to components
Spring Toast Stack React component

What is this?

A toast stack for app feedback. Each result appears as a liquid-glass pill at the bottom-right, with a colored icon, a title, and a short line, and new toasts spring in. Swipe a card sideways to dismiss it. Success, error, and loading are included, and a loading toast can turn into success in the same card. The background is white.

Open the action from a command palette: Spring Command Palette

Use cases

  • SaaS apps that confirm a save without leaving the page.
  • Invite flows that need a short sent confirmation.
  • Uploads that fail with a retry, or that start as loading and turn into success in the same card.

Props

PropTypeDefaultDescription
position"bottom-right" | "bottom-left" | "top-right" | "top-left""bottom-right"Corner the stack anchors to. New toasts enter from that edge.
durationnumber4800Milliseconds before a success or error toast dismisses itself. Loading toasts wait until they change tone.
maxVisiblenumber3How many toasts stay on screen. Older ones wait until a visible toast leaves.
onDismiss(id: string) => void—Called with the toast id after a swipe, the close button, the timer, or dismiss().
closeLabelstringDismiss notificationAccessible name of the close button.
regionLabelstringNotificationsAccessible name of the stack region.
toast()(options) => string—Pushes a toast and returns its id. Pass a title string, or { title, description?, tone?, duration?, id?, actionLabel?, onAction? }. tone is success, error, or loading.
useToast(){ toast, update, dismiss }—The same push, plus update(id, patch) and dismiss(id). update with the same id morphs a loading toast into success without a new card.

Full TSX source. No account needed.

spring-toast-stack.tsx

"use client"; import {  createContext,  useCallback,  useContext,  useEffect,  useId,  useLayoutEffect,  useMemo,  useRef,  useState,  type ReactNode,} from "react";import {  AnimatePresence,  animate,  motion,  useMotionValue,  useReducedMotion,  type PanInfo,} from "motion/react";import { AlarmClock, AlertCircle, Bell, Check, Loader2, MessageCircle, Settings, X } from "lucide-react";import { GlassFilter } from "@/components/ui/liquid-glass";import { coerceDisplayText } from "@/generation/lib/coerceActionNodes";import { cn } from "@/lib/utils"; export type SpringToastPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left"; export type SpringToastTone = "success" | "error" | "loading"; export type SpringToastIcon = "comment" | "reminder" | "build" | "mention"; export type SpringToastOptions = {  id?: string;  title: ReactNode;  description?: ReactNode;  tone?: SpringToastTone;  icon?: SpringToastIcon;  duration?: number;  actionLabel?: ReactNode;  onAction?: () => void;}; type SpringToastRecord = {  id: string;  title: string;  description?: string;  tone: SpringToastTone;  icon?: SpringToastIcon;  duration: number;  actionLabel?: string;  onAction?: () => void;}; export type SpringToastApi = {  toast: (input: SpringToastOptions | string) => string;  update: (id: string, patch: Partial<SpringToastOptions>) => void;  dismiss: (id: string) => void;}; export type SpringToastStackProps = {  position?: SpringToastPosition;  /** Milliseconds before a success or error toast dismisses itself. */  duration?: number;  /** How many toasts stay on screen. Older ones wait behind this cap. */  maxVisible?: number;  onDismiss?: (id: string) => void;  closeLabel?: string;  regionLabel?: string;  className?: string;  children?: ReactNode;}; export type SpringToastStackDemoLabels = {  save: string;  invite: string;  uploadFail: string;  uploadLoading: string;  saved: string;  inviteSent: string;  uploadFailed: string;  retry: string;  uploading: string;  uploadDone: string;  close: string;  region: string;  savedBody: string;  inviteBody: string;  uploadFailedBody: string;  uploadingBody: string;  uploadDoneBody: string;}; export const SPRING_TOAST_STACK_DEMO_LABELS: SpringToastStackDemoLabels = {  save: "Save",  invite: "Send invite",  uploadFail: "Upload (fails)",  uploadLoading: "Upload (loading -> done)",  saved: "Saved",  inviteSent: "Invite sent",  uploadFailed: "Upload failed",  retry: "Retry",  uploading: "Uploading…",  uploadDone: "Upload complete",  close: "Dismiss notification",  region: "Notifications",  savedBody: "Your changes are stored",  inviteBody: "They’ll get an email shortly",  uploadFailedBody: "Check the file and try again",  uploadingBody: "This usually takes a moment",  uploadDoneBody: "The file is ready",}; const SPRING = { type: "spring" as const, stiffness: 460, damping: 34, mass: 0.78 };const STORE_LIMIT = 8;let toastSeq = 0;let activeApi: SpringToastApi | null = null; const SpringToastContext = createContext<SpringToastApi | null>(null); function asPlainString(value: ReactNode | undefined, fallback: string): string {  const text = coerceDisplayText(value);  if (typeof text === "string" && text.trim()) return text;  if (typeof text === "number" || typeof text === "bigint") return String(text);  return fallback;} function usePrefersReducedMotion() {  const fromMotion = useReducedMotion() === true;  const [fromMedia, setFromMedia] = useState(false);   useEffect(() => {    const media = window.matchMedia("(prefers-reduced-motion: reduce)");    const apply = () => setFromMedia(media.matches);    apply();    media.addEventListener("change", apply);    return () => media.removeEventListener("change", apply);  }, []);   return fromMotion || fromMedia;} function nextToastId() {  toastSeq += 1;  return `spring-toast-${toastSeq}`;} /** Push a toast onto the mounted stack. Returns the toast id. */export function toast(input: SpringToastOptions | string): string {  if (!activeApi) return "";  return activeApi.toast(input);} /** `toast`, `update`, and `dismiss` for the nearest stack. */export function useToast(): SpringToastApi {  const ctx = useContext(SpringToastContext);  if (ctx) return ctx;  return {    toast,    update: (id, patch) => activeApi?.update(id, patch),    dismiss: (id) => activeApi?.dismiss(id),  };} const TOAST_ICONS = {  comment: { wrap: "bg-[#d7ebff]", glyph: "text-[#3b82f6]", Icon: MessageCircle },  reminder: { wrap: "bg-[#ffe4c7]", glyph: "text-[#f97316]", Icon: AlarmClock },  build: { wrap: "bg-[#efe0ff]", glyph: "text-[#a855f7]", Icon: Settings },  mention: { wrap: "bg-[#fff1c2]", glyph: "text-[#e0a100]", Icon: Bell },  success: { wrap: "bg-[#dcfce7]", glyph: "text-[#16a34a]", Icon: Check },  error: { wrap: "bg-[#fee2e2]", glyph: "text-[#ef4444]", Icon: AlertCircle },  loading: { wrap: "bg-[#f4f4f5]", glyph: "text-[#52525b]", Icon: Loader2 },} as const; function ToastGlyph({  tone,  icon,  reduce,}: {  tone: SpringToastTone;  icon?: SpringToastIcon;  reduce: boolean;}) {  const spec = TOAST_ICONS[icon ?? tone];  const Glyph = spec.Icon;  return (    <span className={cn("flex size-8 shrink-0 items-center justify-center rounded-full", spec.wrap)}>      <Glyph className={cn("size-4", spec.glyph, tone === "loading" && !icon && !reduce && "animate-spin")} aria-hidden />    </span>  );} function ToastCard({  toast: item,  reduce,  fromTop,  index,  expanded,  paused,  closeLabel,  onDismiss,  onDragLock,}: {  toast: SpringToastRecord;  reduce: boolean;  fromTop: boolean;  index: number;  expanded: boolean;  paused: boolean;  closeLabel: string;  onDismiss: (id: string) => void;  onDragLock: (locked: boolean) => void;}) {  const x = useMotionValue(0);  const lifeKey = `${item.tone}:${item.title}:${item.duration}`;  const remaining = useRef(item.duration);  const lifeRef = useRef(lifeKey);  const onDismissRef = useRef(onDismiss);  onDismissRef.current = onDismiss;  const collapsed = !expanded && index > 0;  const titleId = `${item.id}-title`;   useEffect(() => {    if (lifeRef.current !== lifeKey) {      lifeRef.current = lifeKey;      remaining.current = item.duration;    }    if (item.tone === "loading" || item.duration <= 0 || paused) return;    const start = performance.now();    const left = remaining.current;    const timer = window.setTimeout(() => onDismissRef.current(item.id), left);    return () => {      window.clearTimeout(timer);      if (lifeRef.current !== lifeKey) return;      remaining.current = Math.max(0, left - (performance.now() - start));    };  }, [item.duration, item.id, item.tone, lifeKey, paused]);   const finishDrag = (_event: PointerEvent | MouseEvent | TouchEvent, info: PanInfo) => {    onDragLock(false);    const distance = Math.abs(info.offset.x);    const velocity = Math.abs(info.velocity.x);    const passed = distance > 88 || velocity > 700;    if (!passed) {      void animate(x, 0, SPRING);      return;    }    const direction = info.offset.x < 0 ? -1 : 1;    if (reduce) {      onDismiss(item.id);      return;    }    void animate(x, direction * 280, { type: "spring", stiffness: 420, damping: 32 }).then(      () => onDismiss(item.id),      () => onDismiss(item.id),    );  };   const deckY = fromTop ? index * 12 : index * -12;  const deckScale = 1 - index * 0.045;   return (    <motion.li      layout={!reduce}      className={cn("w-full", collapsed && "absolute inset-x-0")}      style={{        zIndex: 40 - index,        transformOrigin: fromTop ? "top center" : "bottom center",        ...(collapsed ? (fromTop ? { top: 0 } : { bottom: 0 }) : null),      }}      initial={reduce ? { opacity: 0 } : { opacity: 0, y: fromTop ? -24 : 28, scale: 0.98 }}      animate={        reduce || expanded          ? { opacity: 1, y: 0, scale: 1 }          : { opacity: 1, y: deckY, scale: deckScale }      }      exit={reduce ? { opacity: 0, transition: { duration: 0.16 } } : { opacity: 0, transition: { duration: 0.14 } }}      transition={reduce ? { duration: 0.16 } : SPRING}    >      <motion.div        drag={reduce ? false : "x"}        dragMomentum={false}        dragElastic={0.18}        style={{ x }}        onDragStart={() => onDragLock(true)}        onDragEnd={finishDrag}        className="w-full"      >        <article          role="status"          aria-live="polite"          aria-atomic="true"          aria-busy={item.tone === "loading" ? true : undefined}          aria-labelledby={titleId}          className="group relative w-full overflow-hidden rounded-full border border-white/80 text-zinc-950 shadow-[0_10px_28px_rgba(15,23,42,0.16)]"        >          <div            className="pointer-events-none absolute inset-0"            style={{              backdropFilter: "blur(14px) saturate(1.8) url(#glass-distortion)",              WebkitBackdropFilter: "blur(14px) saturate(1.8) url(#glass-distortion)",            }}            aria-hidden          />          <div            className="pointer-events-none absolute inset-0 bg-[linear-gradient(180deg,rgba(255,255,255,0.72)_0%,rgba(255,255,255,0.08)_42%,rgba(255,255,255,0.28)_100%)]"            aria-hidden          />          <div            className="pointer-events-none absolute inset-0 shadow-[inset_0_1px_0_rgba(255,255,255,0.95),inset_0_-1px_0_rgba(255,255,255,0.45)]"            aria-hidden          />          <div className="relative flex w-full items-center gap-2.5 py-1.5 pl-1.5 pr-2">          <AnimatePresence mode="wait" initial={false}>            <motion.span              key={item.icon ?? item.tone}              initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.86 }}              animate={{ opacity: 1, scale: 1 }}              exit={{ opacity: 0, transition: { duration: 0.12 } }}              transition={reduce ? { duration: 0.16 } : SPRING}              className="flex"            >              <ToastGlyph tone={item.tone} icon={item.icon} reduce={reduce} />            </motion.span>          </AnimatePresence>          <div className="min-w-0 flex-1 py-0.5 pr-1">            <AnimatePresence mode="wait" initial={false}>              <motion.div                key={`${item.tone}-${item.title}`}                initial={reduce ? { opacity: 0 } : { opacity: 0, y: 6 }}                animate={{ opacity: 1, y: 0 }}                exit={{ opacity: 0, transition: { duration: 0.12 } }}                transition={reduce ? { duration: 0.16 } : { duration: 0.22 }}              >                <p id={titleId} className="truncate text-[13px] font-semibold leading-4 tracking-tight text-zinc-950">                  {item.title}                </p>                {item.description ? (                  <p className="truncate text-xs leading-4 text-zinc-500">{item.description}</p>                ) : null}              </motion.div>            </AnimatePresence>          </div>          {item.actionLabel ? (            <button              type="button"              onClick={() => item.onAction?.()}              className="shrink-0 rounded-full px-2 py-1 text-xs font-medium text-[#3b82f6] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400"            >              {item.actionLabel}            </button>          ) : null}          <button            type="button"            onClick={() => onDismiss(item.id)}            aria-label={closeLabel}            className="inline-flex size-6 shrink-0 items-center justify-center rounded-full text-zinc-500 hover:bg-white/50 hover:text-zinc-950 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400"          >            <X className="size-3.5" aria-hidden />          </button>          </div>        </article>      </motion.div>    </motion.li>  );} export function SpringToastStack({  position = "bottom-right",  duration = 4800,  maxVisible = 3,  onDismiss,  closeLabel = "Dismiss notification",  regionLabel = "Notifications",  className,  children,}: SpringToastStackProps) {  const reduce = usePrefersReducedMotion();  const fromTop = position.startsWith("top");  const cap = Math.max(1, maxVisible);  const [items, setItems] = useState<SpringToastRecord[]>([]);  const [hovered, setHovered] = useState(false);  const [focused, setFocused] = useState(false);  const [dragging, setDragging] = useState(false);  const durationRef = useRef(duration);  const onDismissRef = useRef(onDismiss);  durationRef.current = duration;  onDismissRef.current = onDismiss;  const reactId = useId();  const [regionId, setRegionId] = useState("spring-toast-stack");   useEffect(() => {    setRegionId(reactId.replace(/:/g, ""));  }, [reactId]);   const dismiss = useCallback((id: string) => {    setItems((prev) => {      if (!prev.some((item) => item.id === id)) return prev;      queueMicrotask(() => onDismissRef.current?.(id));      return prev.filter((item) => item.id !== id);    });  }, []);   const push = useCallback((input: SpringToastOptions | string) => {    const options: SpringToastOptions = typeof input === "string" ? { title: input } : input;    const id = asPlainString(options.id, "").trim() || nextToastId();    const description = options.description == null ? undefined : asPlainString(options.description, "");    const actionLabel = options.actionLabel == null ? undefined : asPlainString(options.actionLabel, "");    const record: SpringToastRecord = {      id,      title: asPlainString(options.title, "Saved"),      description: description || undefined,      tone: options.tone ?? "success",      icon: options.icon,      duration: options.duration ?? durationRef.current,      actionLabel: actionLabel || undefined,      onAction: options.onAction,    };    setItems((prev) => [record, ...prev.filter((item) => item.id !== id)].slice(0, STORE_LIMIT));    return id;  }, []);   const update = useCallback((id: string, patch: Partial<SpringToastOptions>) => {    setItems((prev) =>      prev.map((item) => {        if (item.id !== id) return item;        const description =          patch.description === undefined ? item.description : asPlainString(patch.description, "") || undefined;        const actionLabel =          patch.actionLabel === undefined ? item.actionLabel : asPlainString(patch.actionLabel, "") || undefined;        return {          ...item,          title: patch.title === undefined ? item.title : asPlainString(patch.title, item.title),          description,          tone: patch.tone ?? item.tone,          icon: patch.icon === undefined ? item.icon : patch.icon,          duration: patch.duration ?? item.duration,          actionLabel,          onAction: patch.onAction === undefined ? item.onAction : patch.onAction,        };      }),    );  }, []);   const api = useMemo<SpringToastApi>(() => ({ toast: push, update, dismiss }), [push, update, dismiss]);   useLayoutEffect(() => {    activeApi = api;    return () => {      if (activeApi === api) activeApi = null;    };  }, [api]);   const visible = items.slice(0, cap);  const expanded = true;  const paused = hovered || focused || dragging;  const closeText = asPlainString(closeLabel, "Dismiss notification");  const regionText = asPlainString(regionLabel, "Notifications");   const anchor =    position === "bottom-left"      ? "bottom-10 left-8 items-start"      : position === "top-right"        ? "top-10 right-8 items-end"        : position === "top-left"          ? "top-10 left-8 items-start"          : "bottom-24 right-10 items-end";   const list = (    <ol      className={cn(        "relative flex w-full",        fromTop ? "flex-col gap-2" : "flex-col-reverse gap-2",      )}    >      <AnimatePresence initial={false}>        {visible.map((item, index) => (          <ToastCard            key={item.id}            toast={item}            reduce={reduce}            fromTop={fromTop}            index={index}            expanded={expanded}            paused={paused}            closeLabel={closeText}            onDismiss={dismiss}            onDragLock={setDragging}          />        ))}      </AnimatePresence>    </ol>  );   return (    <SpringToastContext.Provider value={api}>      {children}      <GlassFilter />      <style>{"@keyframes spring-toast-life{from{transform:scaleX(1)}to{transform:scaleX(0)}}"}</style>      <div className={cn("pointer-events-none fixed z-50 flex w-[min(22rem,calc(100vw-2.5rem))]", anchor, className)}>        <div          id={regionId}          role="region"          aria-label={regionText}          className="pointer-events-auto relative w-full"          onPointerEnter={() => setHovered(true)}          onPointerLeave={() => setHovered(false)}          onFocusCapture={() => setFocused(true)}          onBlurCapture={(event) => {            if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setFocused(false);          }}        >          {list}        </div>      </div>    </SpringToastContext.Provider>  );} function DemoButton({ children, onClick }: { children: ReactNode; onClick: () => void }) {  return (    <button      type="button"      onClick={onClick}      className={cn(        "inline-flex min-h-11 items-center rounded-full border border-zinc-200 bg-white px-4 py-2.5 text-sm font-medium text-zinc-900 shadow-sm",        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400 focus-visible:ring-offset-2 focus-visible:ring-offset-white",      )}    >      {children}    </button>  );} function SpringToastStackDemoControls({ labels }: { labels: SpringToastStackDemoLabels }) {  const api = useToast();  const seq = useRef(0);  const timers = useRef<number[]>([]);   useEffect(() => {    const pending = timers.current;    return () => {      for (const timer of pending) window.clearTimeout(timer);    };  }, []);   return (    <div className="flex min-h-screen flex-col items-center justify-center px-6">      <div className="flex max-w-3xl flex-wrap items-center justify-center gap-2">        <DemoButton          onClick={() => api.toast({ title: labels.saved, description: labels.savedBody, tone: "success" })}        >          {labels.save}        </DemoButton>        <DemoButton          onClick={() =>            api.toast({ title: labels.inviteSent, description: labels.inviteBody, tone: "success", icon: "comment" })          }        >          {labels.invite}        </DemoButton>        <DemoButton          onClick={() => {            seq.current += 1;            const id = `demo-fail-${seq.current}`;            api.toast({              id,              title: labels.uploadFailed,              description: labels.uploadFailedBody,              tone: "error",              actionLabel: labels.retry,              onAction: () => api.dismiss(id),            });          }}        >          {labels.uploadFail}        </DemoButton>        <DemoButton          onClick={() => {            seq.current += 1;            const id = `demo-load-${seq.current}`;            api.toast({ id, title: labels.uploading, description: labels.uploadingBody, tone: "loading" });            const timer = window.setTimeout(() => {              api.update(id, { title: labels.uploadDone, description: labels.uploadDoneBody, tone: "success", icon: "build" });            }, 1500);            timers.current.push(timer);          }}        >          {labels.uploadLoading}        </DemoButton>      </div>    </div>  );} export function SpringToastStackDemo({  labels,  className,}: {  labels?: Partial<SpringToastStackDemoLabels>;  className?: string;}) {  const copy = { ...SPRING_TOAST_STACK_DEMO_LABELS, ...labels };   return (    <SpringToastStackStage className={className}>      <SpringToastStack closeLabel={copy.close} regionLabel={copy.region}>        <SpringToastStackDemoControls labels={copy} />      </SpringToastStack>    </SpringToastStackStage>  );} export function SpringToastStackStage({  children,  className,}: {  children?: ReactNode;  className?: string;}) {  return (    <div      data-tsuna-id="spring-toast-stack"      className={cn("relative min-h-screen w-full overflow-hidden bg-white text-zinc-800", className)}    >      <div        className="pointer-events-none absolute -bottom-16 right-[-4rem] size-[42rem] rounded-full bg-[radial-gradient(circle,rgba(56,189,248,0.7),rgba(56,189,248,0)_68%)]"        aria-hidden      />      <div        className="pointer-events-none absolute bottom-10 right-40 size-[32rem] rounded-full bg-[radial-gradient(circle,rgba(244,114,182,0.62),rgba(244,114,182,0)_70%)]"        aria-hidden      />      <div        className="pointer-events-none absolute bottom-36 right-6 size-[22rem] rounded-full bg-[radial-gradient(circle,rgba(167,139,250,0.55),rgba(167,139,250,0)_70%)]"        aria-hidden      />      {children}    </div>  );}

Read the guide

Component

Spring Toast Stack

A toast stack for app feedback. Each result appears as a liquid-glass pill at the bottom-right, with a colored icon, a title, and a short line, and new toasts spring in. Swipe a card sideways to dismiss it. Success, error, and loading are included, and a loading toast can turn into success in the same card. The background is white.

Live Preview

Verified Technical Spec

Animation
Framer Motion
Reduced motion
Verified
Keyboard focus
Verified
Compatibility
Tailwind CSS v3.4 + v4 · React 19 / Next.js 15 App Router + Vite / Remix compatible

Included

  • Copy source into Cursor or Claude for agent install
  • Finished React · TypeScript · Tailwind CSS · Motion · Lucide UI

Dependencies

  • React 19.0.0
  • Typescript 5.7.2
  • Tailwindcss 3.4.16
  • Lucide-react 1.23.0
  • Motion 12.42.2

Tech Stack

  • React
  • TypeScript
  • Tailwind CSS
  • Motion
  • Lucide

Version 1.0.0