Toast
Brief confirmations with an isolated notification queue.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.
Usage
import { Toaster, toast } from '@commenda/pathfinder/toast';
// Mount Toaster once in your application shell.
<>
<Toaster />
<Button
onClick={() =>
toast.show({
title: 'Updated filing',
description: 'Your filing details are up to date.',
tone: 'success',
})
}
>
Show success
</Button>
</>;API reference
| Prop | Type | Default / behavior |
|---|---|---|
Toaster.label | string | Notifications; Alt+T enters stack |
Toaster.direction | ltr | rtl | auto | auto |
toast.show(options) | ToastId | Creates a notification |
toast.update(id, options) | ToastId | Replaces the same notification; pass full options |
toast.dismiss(id?) | void | Dismisses one or all Pathfinder notifications |
title | string | Required, past tense, sentence case |
description | string | Optional concise supporting copy |
tone | neutral | success | info | warning | error | loading | neutral |
id | string | Optional stable task identifier |
actionConfig | FeedbackAction & { appearance?: link | secondary } | One action; secondary only for neutral |
onDismiss | (reason: manual | timeout | swipe) => void | Notification removed from the active queue |
Mount one Toaster in the application shell. Import Pathfinder styles once; no extra Sonner CSS is required. Neutral, success and info expire after 4 seconds; warning, error and loading persist. Hover, keyboard focus, hidden documents and queued messages pause expiry. Replace loading in place with update; never show a second result notification. Body clicks do not dismiss. Actions do not dismiss automatically: call toast.dismiss(id) when appropriate. Never put form validation or required decisions in a toast. This wrapper does not migrate or clear the application’s existing Sonner notifications.
Actions
FeedbackAction requires a label and exactly one of onClick (command) or href (native navigation). Commands support disabled, disabledReason, loadingConfig, and leadingIcon; navigation supports target, rel, and leadingIcon. The application owns async work and retry state.
Examples
Tones
Actions
Update
Read the design guidance before using these components.
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Toast — 316:2
- TOAST-01: Confirm a recent save, send or copy. Required decisions and durable problems belong in inline Alert. Never use a toast for form validation. Title uses past tense, sentence case, no period; description adds concise supporting text.
- TOAST-02: Neutral has no icon; success/info/warning/error use the solid 16 px glyphs from 464:357, not outline substitutes. Neutral/info/success expire after 4 seconds; warning/error/loading persist. Pause on hover, keyboard focus or hidden document. Queued messages get their reading time once visible.
- TOAST-03: Loading updates to its result under the same ID. One action maximum, normally a link; never a primary Button. Actions only dismiss when application code requests it. Body clicks do not dismiss.
- TOAST-04: Bottom center above overlays; three visible, newest in front. Collapsed peek 14 px at 0.95 scale; expanded gap 8. Width 356 with viewport/safe-area caps, white background, pearl 300 hairline, radius 10, panel elevation, padding 12/16, gap 10. Enter 400 ms ease-out, exit 200 ms; honor reduced motion. Close has a 16 px visible circle and a larger target. Alt+T enters the stack.
- TOAST-05: Mount one Pathfinder Toaster. A dedicated Sonner toaster ID and prefixed notification IDs isolate notifications from the existing application toaster. Pathfinder dismiss-all only dismisses its own active IDs. The scoped upstream structural stylesheet is a documented adapter exception to utility-only component styling; applications import only Pathfinder's finished CSS.