Duolith docs

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**, with dismissToast(id). Options are tone (neutral, success, danger), action ({ label, onPress }) and duration (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 Toast part 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

OptionWhy 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 partToasts 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:openEvery 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) gains toast, dismissToast, pressToastAction and visibleToasts, and the types Toast, ToastAction, ToastOptions and ToastTone.
  • Native targets will read the same queue and show it with the platform's toast or snackbar look.