Toast

Toast is the app-owned toast data type. ToasterWidget is the stateless paint-only widget that renders a stack of visible toasts. Toasts are not focusable components and do not own timers.

There is no dedicated toast demo. The Button and Dialog demos render toast notifications with ToasterWidget.

State Model

Your app owns the toast list and lifecycle. A common pattern is to store a start time next to each toast, derive its age while rendering, and periodically remove expired entries.

use std::time::{Duration, Instant};
use ratcn::{Toast, ToastKind, ToastPosition, ToasterWidget};

struct AppToast {
    toast: Toast<'static>,
    started_at: Instant,
}

struct AppState {
    toasts: Vec<AppToast>,
    theme: Theme,
}

state.toasts.push(AppToast {
    toast: Toast::success("Saved").description("Your changes were written."),
    started_at: Instant::now(),
});

Render by deriving aged Toast values and passing a slice to ToasterWidget.

let now = Instant::now();
let visible = state
    .toasts
    .iter()
    .map(|item| item.toast.clone().age(now.duration_since(item.started_at)))
    .collect::<Vec<_>>();

frame.render_widget(
    ToasterWidget::new(&visible)
        .themed(&state.theme)
        .position(ToastPosition::BottomRight)
        .visible_toasts(3),
    frame.area(),
);

Toast API

Method	Description
Toast::new(title)	Creates a default toast with a 4 second duration.
Toast::success(title)	Creates a success toast.
Toast::error(title)	Creates an error toast.
Toast::warning(title)	Creates a warning toast.
Toast::info(title)	Creates an info toast.
Toast::loading(title)	Creates a loading toast.
.description(text)	Adds secondary text below the title.
.kind(ToastKind::...)	Sets the kind explicitly.
.duration(duration)	Sets the expiration duration.
.persistent()	Makes the toast never expire.
.age(duration)	Sets the derived age used by is_expired().
.border(bool)	Toggles the border around this toast.
.is_expired()	Returns whether age >= duration; persistent toasts never expire.

ToastKind

ToastKind controls the accent color and icon text. Values are Default, Success, Error, Warning, Info, and Loading.

ToasterWidget API

Method	Description
ToasterWidget::new(&toasts)	Creates a toast stack renderer.
.themed(&theme)	Applies theme colors.
.position(ToastPosition::...)	Sets the screen corner or edge alignment. Defaults to BottomRight.
.width(width)	Sets the toast stack width. Defaults to 42.
.gap(rows)	Sets rows between toasts. Defaults to 1.
.visible_toasts(count)	Limits how many non-expired toasts render. Defaults to 3.
.offset(x, y)	Insets the stack from the selected edge. Defaults to 1, 1.
.visible()	Returns the visible non-expired toasts in render order.

ToastPosition supports TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, and BottomRight.

Events

Toast and ToasterWidget handle no events. Add, age, and remove toasts in app state, usually from normal app messages and tick events.

Lifecycle

ToasterWidget filters expired toasts but does not mutate your list. Keep that cleanup in app code, typically on a tick event:

state.toasts.retain(|item| {
    !item.toast
        .clone()
        .age(now.duration_since(item.started_at))
        .is_expired()
});