Arc

Toast stack

Stack short results at the edge until you reach for them.

pnpm dlx shadcn@latest add @uiarc/toast-stack
Live · keyboard ready

Northwind release desk

    • App-wide notifications for async results, errors, and undo.
    • Loading toasts that morph into success or error when work finishes.
    • Toasts with an action button, like View or Undo.
    • Use toast for a single locally controlled confirmation.
    • Use alert for persistent messages tied to a page.
    • Use notification-center for a history people can come back to.

    Installation

    Add Toast stack with the shadcn CLI, or copy the source by hand.

    pnpm dlx shadcn@latest add @uiarc/toast-stack

    Adds the component and its local dependencies, and installs motion, lucide-react. First time? Add the @uiarc registry to components.json, or use the full URL:

    example.tsx
    import { ToastStack, ToastStackProvider, useToastStack } from "@/registry/components/toast-stack/toast-stack"; function PublishButton() {  const { toast, update } = useToastStack();  async function publish() {    const id = toast({ type: "loading", title: "Publishing" });    await api.publish();    update(id, { type: "success", title: "Published", action: { label: "View", onClick: openSite } });  }  return <button type="button" onClick={publish}>Publish</button>;} export function App() {  return <ToastStackProvider><PublishButton /><ToastStack /></ToastStackProvider>;}

    Undo action

    example.tsx
    const { toast, dismiss } = useToastStack(); toast({  type: "info",  title: "Message archived",  action: { label: "Undo", onClick: id => { restore(); dismiss(id); } },});

    API reference

    3 parts. The first is the root.

    ToastStackProvider

    Scopes a toast queue to its subtree. Wrap the app or panel once.

    PropTypeDefaultDescription
    childrenRequiredReactNode–Subtree that can raise toasts.
    durationnumber5000Base lifetime in ms. Warnings and errors stay 1.6 times longer; loading waits for an update.
    limitnumber12Oldest toasts beyond this count are dropped.

    ToastStack

    The viewport. Toasts rise from the bottom, tuck behind each other, and fan out on hover or focus.

    PropTypeDefaultDescription
    labelstring"Notifications"Accessible name of the region.
    position"bottom-right" | "bottom-center" | "bottom-left""bottom-right"Corner of the viewport.
    containedbooleanfalsePins the stack inside the nearest positioned ancestor instead of the window.
    visibleToastsnumber3How many toasts show at once.
    hotkeybooleantrueAlt+T moves focus into the stack.
    classNamestring–Class on the region.

    useToastStack

    Hook returning { toast, update, dismiss, count }. Must be called inside ToastStackProvider.

    PropTypeDefaultDescription
    toast(options: ToastOptions) => string–Shows a toast and returns its id. Options: id, type ("success" | "info" | "warning" | "error" | "loading"), title, description, action { label, onClick(id) }, duration.
    update(id: string, patch: Partial<Omit<ToastOptions, "id">>) => void–Morphs a toast in place and restarts its timer. Pass action: undefined to remove the action.
    dismiss(id?: string) => void–Dismisses one toast, or all when called without an id.
    countnumber–How many toasts are queued.
    Alt+T
    Moves focus to the front toast and fans out the stack.
    Tab
    Moves between toast actions and dismiss buttons.
    Escape
    Dismisses the focused toast.
    • The viewport is a labelled section with aria-live="polite" and aria-relevant="additions text", so new and updated toasts are announced.
    • Each toast prefixes a screen-reader-only type label such as "Error:"; outgoing copy is aria-hidden while it fades.
    • Hidden and leaving toasts are inert. When a focused toast closes, keyboard focus moves to the next toast or back to where it came from.
    • Timers pause while the stack is hovered, focused, dragged, or the tab is hidden.
    • New toasts rise from their own height below the edge; older ones tuck behind at 14px peeks and 0.05 scale steps, and fan out on a morph spring.
    • Swiping right follows the finger and throws with velocity; left rubber-bands. Updates morph the icon, copy, height, and action width in place.
    • Reduced motion jumps positions and uses short opacity fades.
    • The viewport is min(22.5rem, 100% minus a 32px gutter) wide; below 30rem it centers at the bottom regardless of position.
    • Below a 21rem toast width the action button drops under the copy instead of squeezing it.
    • On touch, a tap fans out the stack, and a right swipe dismisses a toast.
    • At most 12 toasts are kept by default and only 3 show; each has its own ResizeObserver for height.
    • Timers pause while hovered, focused, dragged, or when the tab is hidden.

    Notes for AI

    Give your coding assistant the Markdown reference instead of screenshots.

    • Default for app-wide notifications, async results, and undo. Use toast for a single locally controlled confirmation and alert for persistent inline messages.
    • Render ToastStack once inside ToastStackProvider and call useToastStack anywhere below. Reuse an id or call update to morph loading into success or error.
    /components/toast-stack/markdown

    The full library index for assistants is at /llms.txt.

    ToastComponentBrief confirmation for a completed background action.AlertComponentA persistent message that helps people recover or continue.Hold to confirmComponentConfirm a destructive action by holding, not tapping.