Toasts

Toasts provide brief, non-blocking feedback while the user continues working. Access them through ctx.toast after requesting the api.toast permission.

{
  "recall": {
    "permissions": ["api.toast"]
  }
}

Choose a method that matches the message:

Method	Use for
message()	Neutral feedback
success()	A completed action
info()	Status or contextual information
warning()	A non-blocking caution
error()	A failure the current flow has already handled

await ctx.toast.success({
  title: "Deck saved",
  description: "Your latest changes are available offline.",
});

Options

Every toast method accepts the same options:

Option	Type	Description
title	string	Short primary message.
description	string	Optional supporting detail.
duration	number	Optional display duration in milliseconds.
dismissible	boolean	Whether the user can dismiss the toast early.
action	ToastAction	Optional primary follow-up action, such as retry or undo.
cancel	ToastAction	Optional secondary action.

A toast action has a short label and an optional onPress callback:

await ctx.toast.error({
  title: "Could not save changes",
  description: "Check your connection and try again.",
  action: {
    label: "Retry",
    onPress: retrySave,
  },
});

The flow must remain safe when the user ignores an action. Do not make a toast action the only way to recover important work.

Lifecycle

Calling a toast method creates and opens one temporary toast. There is no registration or lifecycle-event API. The app handles its placement, queue, dismissal, and disposal.

Awaiting a toast method only confirms that the host accepted the request; it does not wait for dismissal or an action. Use a dialog when the user must acknowledge a message or decide whether an action should continue.