0036. toast() is a runtime function from @duolith/client, shown by the kit's Toast region
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP7 (kit, overlays)
Context
Toasts are shown from code, not markup: after an action succeeds, in a handler, from a data layer callback. Pages need one call, such as toast("Saved", { action }), that works from any script. Something must also show them: a region, styled by the kit and themed like every part, that is a live region, queues, pauses and can be swiped.
Decision
- **
toast(message, options?)is exported by@duolith/client**, withdismissToast(id). Options aretone(neutral,success,danger),action({ label, onPress }) andduration(5 seconds, 8 with an action). It returns the toast's id. - The queue is runtime state, platform-neutral (
packages/client/src/toasts.ts): at most three toasts show, the rest wait; each visible toast's clock runs only while toasts are not paused, and keeps the time it has left.visibleToasts()is what a region reads; reading it in a view tracks it. - **The kit's
Toastpart is the region**, placed once per page (or in a layout when layouts exist):<overlay kind="toasts">with a list of the visible toasts. The overlay layer pauses the queue while the region is hovered or holds focus, and dismisses a toast swiped sideways. Error (danger) toasts are alerts, announced at once; the others are announced politely by the region.
Alternatives considered
| Option | Why not |
|---|---|
import { toast } from "@duolith/kit" | @duolith/kit exports only parts, checked by name at build time (E0123, decision 0028); a function there would be a second kind of kit export and need the compiler to carry runtime code for the kit |
| The runtime draws toasts itself, with no part | Toasts would not be themed or overridable like the other parts, and native would need a second implementation of the look |
A <Toast> placed per message, opened with bind:open | Every page would manage a queue, timers and pause by hand |
Consequences
- A page that calls
toast()without placing<Toast />shows nothing; the guide says to place it once. - The runtime API (
packages/client) gainstoast,dismissToast,pressToastActionandvisibleToasts, and the typesToast,ToastAction,ToastOptionsandToastTone. - Native targets will read the same queue and show it with the platform's toast or snackbar look.