@pyreon/toast — API Reference

Generated from toast's src/manifest.ts — the same source that powers llms.txt and MCP get_api. Do not edit this page by hand; edit the manifest. For the conceptual guide, see toast.

Imperative toast notifications for Pyreon. Call toast() from anywhere in your app — no provider or context needed. Preset variants (toast.success, toast.error, etc.), a toast.promise() helper for async operations, and toast.update() for loading-to-success patterns. Render <Toaster /> once at the app root — it uses Portal, animated enter/leave CSS transitions, auto-dismiss, and a countdown that suspends on hover, on keyboard focus, and while the tab is hidden. Accessible with a type-aware live-region role — role="alert" (assertive) for error/warning, role="status" (polite) for info/success — plus aria-atomic.

Peer dependencies: @pyreon/runtime-dom — install alongside this package.

Features

toast() imperative API — call from anywhere, no provider needed
toast.success/error/warning/info/loading preset variants
toast.update(id, options) for loading-to-success transitions
toast.promise(promise, messages) auto-transitions through states
toast.dismiss(id?) — soft-dismiss one or all (plays the CSS leave animation)
toast.remove(id?) — hard-remove one or all instantly (no leave animation)
Per-toast description (secondary line), custom icon, and action button
Animated enter AND leave — a dismissed toast fades + collapses in place, siblings reflow smoothly
<Toaster /> with Portal, CSS transitions, auto-dismiss, a countdown suspended on hover / focus / a hidden tab, configurable default duration
Accessible: type-aware live regions — role="alert" (assertive) for error/warning, role="status" (polite) for info/success

Complete example

A full, end-to-end usage of the package:

import { toast, Toaster } from '@pyreon/toast'

// Mount Toaster once at app root:
function App() {
  return (
    <>
      <Toaster position="top-right" duration={4000} />
      <MainContent />
    </>
  )
}

// Call toast() from anywhere — no provider needed:
toast('Hello!')

// Preset variants:
toast.success('Saved successfully!')
toast.error('Something went wrong')
toast.warning('Session expiring soon')
toast.info('New version available')

// Loading → success pattern:
const id = toast.loading('Saving...')
try {
  await saveData()
  toast.update(id, { type: 'success', message: 'Done!' })
} catch {
  toast.update(id, { type: 'error', message: 'Save failed' })
}

// Promise helper — auto-transitions through states:
toast.promise(fetchData(), {
  loading: 'Loading...',
  success: 'Loaded!',
  error: 'Failed to load',
})

// Dismiss (soft — animates out) or remove (hard — instant):
const toastId = toast('Dismissable')
toast.dismiss(toastId)  // soft-dismiss one (plays the leave animation)
toast.dismiss()         // soft-dismiss all
toast.remove(toastId)   // hard-remove one (no animation)
toast.remove()          // hard-remove all

Exports

Symbol	Kind	Summary
`toast`	function	Create a toast notification imperatively.
`Toaster`	component	Render container for toast notifications.

API

toast `function`

(message: string, options?: ToastOptions) => string

Create a toast notification imperatively. Returns the toast ID for later update() or dismiss(). Works from anywhere in the app — no context or provider needed. Options include type, duration (0 = persistent), description (a secondary line), icon (any VNode), action (a button), dismissible, and onDismiss. The function also exposes .success(), .error(), .warning(), .info(), .loading() preset methods, .update(id, options) for modifying an existing toast (message/type/duration/description), .dismiss(id?) for SOFT removal (plays the CSS leave animation, then removes), .remove(id?) for HARD instant removal (no animation), and .promise(promise, messages) for async operation tracking.

Example

// Basic:
toast('Hello!')
const id = toast.success('Saved!')

// With a description + custom icon:
toast.success('Uploaded', { description: '3 files · 1.2 MB', icon: <CheckIcon /> })

// Loading → success:
const loadId = toast.loading('Saving...')
await save()
toast.update(loadId, { type: 'success', message: 'Done!' })

// Promise helper:
toast.promise(fetchData(), {
  loading: 'Loading...',
  success: 'Loaded!',
  error: 'Failed',
})

// Dismiss:
toast.dismiss(id)  // one
toast.dismiss()    // all

Common mistakes

Forgetting to render <Toaster /> — toasts are created but have no visual container to render into
Calling toast.update() after the toast has been auto-dismissed — the ID is no longer valid, the update is silently ignored
Using toast.promise() with a function instead of a promise — pass the promise directly, not () => fetch(...)
Expecting toast.dismiss(id) to remove the toast synchronously — it is SOFT (plays the ~200ms leave animation first); reach for toast.remove(id) when you need it gone instantly
toast.loading() never auto-dismisses — it is created with duration: 0 (persistent). You MUST resolve it yourself via toast.update(id, …) / toast.dismiss(id) / toast.remove(id), or use toast.promise() which settles it for you. A forgotten loading toast stays on screen forever.
Reading duration: 0 as "dismiss immediately" — duration <= 0 skips the auto-dismiss timer entirely, so the toast is PERSISTENT. To remove one now, call toast.remove(id); 0 means "stay until dismissed".
toast.update(id, …) only changes message / type / duration / description — NOT icon or action. To swap the icon or action button, dismiss and re-create the toast.
toast.promise(p, …) still REJECTS — it returns the ORIGINAL promise, so a rejection propagates past the error toast; add your own .catch() if you need to handle it. success / error may also be FUNCTIONS receiving the resolved value / error (e.g. success: (data) => "Saved " + data.id).

See also: Toaster

Toaster `component`

(props?: ToasterProps) => VNodeChild

Render container for toast notifications. Mount once at the app root. Renders via Portal with CSS transitions, auto-dismiss timer, and a countdown suspended on hover, on keyboard focus, and while the tab is hidden. Position configurable via position prop (top-right, top-left, bottom-right, bottom-left, top-center, bottom-center). Duration configurable via duration prop (default 4000ms).

Example

<Toaster position="top-right" duration={5000} />

Common mistakes

Mounting multiple <Toaster /> instances — toasts render in all of them, causing duplicates
Conditional rendering of <Toaster /> — if unmounted, toasts created via toast() are queued but invisible until the Toaster mounts

See also: toast

Package-level notes

No provider needed: Unlike most Pyreon packages, toast uses a module-level signal store — toast() works from event handlers, effects, or any non-component code. The <Toaster /> component reads from this shared store.

Peer dep: @pyreon/runtime-dom is required because <Toaster /> JSX emits _tpl() calls — declare it in consumer app dependencies.

When the countdown is suspended: The auto-dismiss timer suspends while the pointer is over the stack, while keyboard focus is inside it, and while the tab is hidden — a four-second toast is four seconds of ATTENTION, not of wall clock, so one raised just before the user switches tabs is still there when they come back. The three are INDEPENDENT holds: releasing one (a mouseleave) does not restart the clock while another (focus still inside) is outstanding. Built into <Toaster /> with no configuration needed.