ui/components/toast

Toast

Terminal-styled toast notification system. Imperative toast() API callable from anywhere. Supports tone shortcuts (severity), four layout variants, promise handling, and position-aware animations.

Preview

tsx

1 "use client";2 3 import { useEffect } from "react";4 import { toast } from "@/components/ui/toast";5 6 export default function ToastStatic() {7   // Publishes one standing toast to the store on mount so this page shows a8   // real rendered toast instead of only trigger buttons. A non-finite duration9   // opts out of auto-dismissal; the close button still removes it.10   useEffect(() => {11     const id = toast.success("Patch applied", {12       message: "Modified 2 files in src/auth/.",13       duration: Number.POSITIVE_INFINITY,14     });15     return () => toast.dismiss(id);16   }, []);17 18   return (19     <p className="font-mono text-xs text-muted-foreground">20       Toasts render in a fixed-position region — look at the bottom-right corner of the page.21     </p>22   );23 }24

Installation

$pnpm exec dgadd add ui/toast

[Installs to]src/components/ui/toast[Item]ui/toast

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import { toast } from "@/components/ui/toast";5 6 export default function ToastDefault() {7   return (8     <div className="flex flex-wrap gap-2">9       <Button10         variant="primary"11         size="sm"12         onClick={() => toast.success("Saved", { message: "Changes saved successfully." })}13       >14         Success15       </Button>16       <Button17         variant="destructive"18         size="sm"19         onClick={() => toast.error("Error", { message: "Something went wrong." })}20       >21         Error22       </Button>23       <Button24         variant="secondary"25         size="sm"26         onClick={() => toast.warning("Warning", { message: "This action cannot be undone." })}27       >28         Warning29       </Button>30       <Button31         variant="ghost"32         size="sm"33         onClick={() => toast.info("Info", { message: "A new version is available." })}34       >35         Info36       </Button>37     </div>38   );39 }40

Examples

All Tones

Preview

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import { toast } from "@/components/ui/toast";5 6 export default function ToastDefault() {7   return (8     <div className="flex flex-wrap gap-2">9       <Button10         variant="primary"11         size="sm"12         onClick={() => toast.success("Saved", { message: "Changes saved successfully." })}13       >14         Success15       </Button>16       <Button17         variant="destructive"18         size="sm"19         onClick={() => toast.error("Error", { message: "Something went wrong." })}20       >21         Error22       </Button>23       <Button24         variant="secondary"25         size="sm"26         onClick={() => toast.warning("Warning", { message: "This action cannot be undone." })}27       >28         Warning29       </Button>30       <Button31         variant="ghost"32         size="sm"33         onClick={() => toast.info("Info", { message: "A new version is available." })}34       >35         Info36       </Button>37     </div>38   );39 }40

Layout Variants

Preview

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import { toast } from "@/components/ui/toast";5 6 export default function ToastVariants() {7   return (8     <div className="flex flex-wrap gap-2">9       <Button10         variant="primary"11         size="sm"12         onClick={() =>13           toast("Branch merged", {14             tone: "success",15             variant: "hud",16             message: "main · 2 files",17           })18         }19       >20         HUD pill21       </Button>22       <Button23         variant="primary"24         size="sm"25         onClick={() =>26           toast("Patch applied", {27             tone: "success",28             variant: "card",29             message: "Modified 2 files in src/auth/.",30           })31         }32       >33         Card (default)34       </Button>35       <Button36         variant="primary"37         size="sm"38         onClick={() =>39           toast("Stale artifacts", {40             tone: "warning",41             variant: "viewfinder",42             message: "Run pnpm prepare:artifacts before validating.",43           })44         }45       >46         Viewfinder47       </Button>48       <Button49         variant="primary"50         size="sm"51         onClick={() =>52           toast("Synced", {53             tone: "info",54             variant: "countdown",55             message: "Synced 12 files from origin.",56             duration: 5000,57           })58         }59       >60         Countdown61       </Button>62     </div>63   );64 }65

With Actions

Preview

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import { toast } from "@/components/ui/toast";5 6 const REVIEW_SUBMITTED_TOAST_ID = "review-submitted";7 8 export default function ToastActions() {9   return (10     <div className="flex flex-col gap-4">11       <Button12         variant="primary"13         size="sm"14         onClick={() =>15           toast.success("Review Submitted", {16             id: REVIEW_SUBMITTED_TOAST_ID,17             message: "Your code review has been submitted for 3 files.",18             action: (19               <Button20                 variant="ghost"21                 size="sm"22                 bracket23                 className="px-0"24                 onClick={() => toast.dismiss(REVIEW_SUBMITTED_TOAST_ID)}25               >26                 Dismiss27               </Button>28             ),29           })30         }31       >32         Show with Action33       </Button>34       <Button35         variant="secondary"36         size="sm"37         onClick={() =>38           toast.info("Analysis Complete", {39             message: "Found 5 suggestions and 2 warnings across 12 files.",40             duration: 8000,41           })42         }43       >44         Show with Custom Duration (8s)45       </Button>46     </div>47   );48 }49

Positions

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { Toaster, toast } from "@/components/ui/toast";6 import { createToggleGroup } from "@/components/ui/toggle-group";7 8 const ToastPositionGroup = createToggleGroup([9   "top-left",10   "top-center",11   "top-right",12   "bottom-left",13   "bottom-center",14   "bottom-right",15 ] as const);16 17 type ToastPositionValue = (typeof ToastPositionGroup.values)[number];18 19 export default function ToastPositions() {20   const [position, setPosition] = useState<ToastPositionValue | null>("bottom-right");21 22   return (23     <div className="flex flex-col gap-4">24       <ToastPositionGroup label="Toast position" value={position} onChange={setPosition}>25         <ToastPositionGroup.Item value="top-left">Top Left</ToastPositionGroup.Item>26         <ToastPositionGroup.Item value="top-center">Top Center</ToastPositionGroup.Item>27         <ToastPositionGroup.Item value="top-right">Top Right</ToastPositionGroup.Item>28         <ToastPositionGroup.Item value="bottom-left">Bottom Left</ToastPositionGroup.Item>29         <ToastPositionGroup.Item value="bottom-center">Bottom Center</ToastPositionGroup.Item>30         <ToastPositionGroup.Item value="bottom-right">Bottom Right</ToastPositionGroup.Item>31       </ToastPositionGroup>32       <Button33         variant="primary"34         size="sm"35         onClick={() => toast.info("Notification", { message: "Check the selected corner." })}36       >37         Show Toast38       </Button>39       <Toaster position={position ?? "bottom-right"} />40     </div>41   );42 }43

Promise

Preview

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import { toast } from "@/components/ui/toast";5 6 function simulateAsync(shouldFail = false): Promise<{ count: number }> {7   return new Promise((resolve, reject) => {8     setTimeout(() => {9       if (shouldFail) reject(new Error("Network error"));10       else resolve({ count: 12 });11     }, 2000);12   });13 }14 15 export default function ToastPromise() {16   return (17     <div className="flex flex-wrap gap-2">18       <Button19         variant="primary"20         size="sm"21         onClick={() =>22           toast.promise(simulateAsync(), {23             loading: "Analyzing files...",24             success: (data) => `Analysis complete: ${data.count} files`,25             error: "Analysis failed",26           })27         }28       >29         Promise (Success)30       </Button>31       <Button32         variant="destructive"33         size="sm"34         onClick={() =>35           toast36             .promise(simulateAsync(true), {37               loading: "Analyzing files...",38               success: "Done",39               error: (err) => (err instanceof Error ? err.message : "Unknown error"),40             })41             // toast.promise returns a promise that rejects when the input rejects.42             .catch(() => {})43         }44       >45         Promise (Error)46       </Button>47     </div>48   );49 }50

Loading

Preview

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import { toast } from "@/components/ui/toast";5 6 export default function ToastLoading() {7   return (8     <div className="flex flex-wrap gap-2">9       <Button10         variant="secondary"11         size="sm"12         onClick={() => toast.loading("Processing...", { message: "This may take a moment." })}13       >14         Show Loading Toast15       </Button>16       <Button variant="ghost" size="sm" onClick={() => toast.dismiss()}>17         Dismiss All18       </Button>19     </div>20   );21 }22

API Reference

Toaster

Name	Type	Default	Description
position	"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"	"bottom-right"	Corner where toasts stack. Drives positioning classes and slide-in direction.
hotkey	string	"F8"	Key that moves DOM focus to the toast region. For timed toasts this hotkey (or Tab) is the intended keyboard route — they are exempt from arrow entry because focus on a timer-unmounted element would strand the user; persistent toasts are additionally entered through focusToastRegion, and inside the region ArrowUp/ArrowDown walk the controls either way. Matched against KeyboardEvent.key and ignored while an editable element has focus. Defaults to F8, the Radix viewport hotkey.
label	string	"Notifications"	Accessible name for the toast region landmark.

toast (function)

Name	Type	Default	Description
titlerequired	string	—	Primary toast title (first positional argument).
tone	"success" \| "error" \| "warning" \| "info" \| "loading"	"info"	Severity tone. Drives icon, color, and auto-dismiss behavior. Error and loading tones persist when duration is omitted, except in the `hud` variant which auto-dismisses on the default timer.
variant	"card" \| "hud" \| "viewfinder" \| "countdown"	"card"	Visual style variant / layout shell. `card` is the default two-row layout; `hud` is a single-line pill with no body, action, or close button; `viewfinder` has corner brackets; `countdown` adds an auto-dismiss progress bar.
message	string	—	Message content: secondary detail text below the title (rendered inline as muted text in `hud`).
duration	number	5000	Auto-dismiss delay in ms. Error/loading tones and toasts with a rendered action persist when duration is omitted. The `hud` variant does not render actions or a close button, so it auto-dismisses on the default timer even for error and loading tones. An explicit positive duration schedules dismissal; a non-finite duration (Infinity) opts out of auto-dismissal entirely.
action	ReactNode	—	Action element (e.g. a Button) rendered under the message. The `hud` variant silently omits it.
dismissLabel	string	"Dismiss: " + title	Accessible name for the dismiss button. The `hud` variant does not render a close button, so this prop has no effect there.
toneLabel	string	the tone value	Accessible tone label: screen-reader tone text announced before the toast title.
id	string	auto-generated	ID applied to the rendered element; stable id for updating an existing toast (used by toast.promise to swap loading -> success/error).

Accessibility

Keyboard Navigation

Press Escape to dismiss every visible toast at once. Toast Escape handling is global while toasts are present and runs before lower-priority page overlays unless another handler has already consumed the key. Press the focus hotkey (F8 by default, configurable via the Toaster `hotkey` prop) to move focus into the toast region.

Notes

Imperative API

Call toast(), toast.success(), toast.error(), toast.warning(), toast.info(), or toast.loading() from any code — no provider required. Place a <Toaster /> component in your app layout to render toasts.

Tone vs Variant

`tone` is severity (success/error/warning/info/loading) and drives color and ARIA role. `variant` is the layout shell: `card` (default, full payload), `hud` (single-line pill), `viewfinder` (corner brackets), `countdown` (card + auto-dismiss progress bar).

Promise Support

toast.promise(asyncFn, { loading, success, error }) shows a loading toast that updates to success or error when the promise settles. It returns the input promise and rejects when the input rejects, so callers must handle rejection with await/try-catch or .catch().

Loading Toasts

Loading toasts show a braille spinner and persist when duration is omitted. Use toast.loading() for manual control, or toast.promise() for automatic lifecycle. An explicit positive duration schedules auto-dismissal.

Error Toasts Persist

Toasts with tone='error' persist when duration is omitted and must be closed manually. An explicit positive duration schedules auto-dismissal. The `hud` variant omits the close button and auto-dismisses even for error and loading tones; pass a non-finite duration (Infinity) to opt out.

Actions

Render the `action` slot with the bracketed ghost Button (`<Button variant="ghost" size="sm" bracket>`) so a toast invitation speaks the same [ label ] vocabulary as the rest of the library. A toast with a rendered action and no explicit duration persists until dismissed.

Keyboard

Press Escape to dismiss every visible toast at once, so the key a screen advertises for Escape is at most one extra press away even after an error burst. Toast Escape handling is global when toasts are present, so it runs before lower-priority page overlays that have not already handled the key. Press the focus hotkey (F8 by default, configurable via the Toaster `hotkey` prop) to move focus into the toast region so action and close buttons stay reachable before a timed toast disappears; the hotkey is ignored while an editable element has focus.

Pause Behavior (WCAG 2.2.1)

Auto-dismiss timers pause while the pointer hovers the toaster region, while focus is inside it (so action buttons stay reachable by keyboard), and while the document tab is hidden. Timers resume from the remaining time once interaction ends — users never lose time they could not see or read.

Source

Install via CLI: pnpm exec dgadd add ui/toast. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Toast

Installation

Usage

Examples

All Tones

Layout Variants

With Actions

Positions

Promise

Loading

API Reference

Toaster

toast (function)

Accessibility

Keyboard Navigation

Notes

Imperative API

Tone vs Variant

Promise Support

Loading Toasts

Error Toasts Persist

Actions

Keyboard

Pause Behavior (WCAG 2.2.1)

Source

View component source (33 files)