Toast

ui.toast draws a notification with a title, a message, actions and a close button; kind is "info", "success", "warning" or "error". ui.toasts(base, items) stacks them in the bottom-right corner over your view.

ui.toast · Category: Overlays · Full reference →

Preview
Code

pz.column([
    ui.toast("Saved", "main.py was saved.", kind="success", on_dismiss=on_dismiss),
    ui.toast("Update available", "Pyzed 0.4 is on PyPI.", kind="info",
             actions=[ui.button("What's new", on_open, size="sm")], on_dismiss=on_dismiss),
    ui.toast("Could not connect", kind="error", on_dismiss=on_dismiss),
], spacing=8)

When to use

To confirm something that happened in the background (saved, copied, connected).
Messages that need an answer belong in a Dialog.

Usage

import pyzed as pz
from pyzed import ui

import threading

class Notes(pz.App):
    def __init__(self):
        self.messages = []

    def notify(self, title):
        self.messages.append(title)
        threading.Timer(3, pz.post, args=(("expire", title),)).start()  # hide it after 3 s

    def update(self, message):
        if message[0] == "expire":
            self.messages.remove(message[1])

    def view(self):
        items = [ui.toast(m, kind="success", on_dismiss=lambda m=m: self.messages.remove(m))
                 for m in self.messages]
        return ui.toasts(self.main_view(), items)

Variants

Kind

Toast: kind="success" — `kind="success"`

Toast: kind="warning" — `kind="warning"`

Content

Toast: actions=, on_dismiss= — `actions=, on_dismiss=`

States and events

Events

Toast has 2 events of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Event	Handler gets	When
`on_dismiss`	`()`	Message or callable sent on close.
`on_press`	`()`	Makes the card clickable.

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

class Notes(pz.App):
    def __init__(self):
        self.messages = ["Saved"]
        self.opened = 0

    def view(self):
        items = [ui.toast(m, kind="success",
                          on_dismiss=lambda m=m: self.messages.remove(m),           # its ✕
                          on_press=lambda: setattr(self, "opened", self.opened + 1))  # the card
                 for m in self.messages]
        return ui.toasts(main_view(), items)

from dataclasses import dataclass


@dataclass
class Dismiss:
    text: str


class Notes(pz.App):
    messages = ["Saved"]

    def update(self, message):
        match message:
            case Dismiss(text):
                self.messages = [m for m in self.messages if m != text]

    def view(self):
        return ui.toasts(main_view(), [ui.toast(m, kind="success", on_dismiss=Dismiss(m))
                                       for m in self.messages])

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    messages: tuple = ("Saved",)


def view(state, set_state):
    close = lambda m: set_state(messages=tuple(x for x in state.messages if x != m))
    return ui.toasts(main_view(), [ui.toast(m, kind="success", on_dismiss=lambda m=m: close(m))
                                   for m in state.messages])

Properties and API

`ui.toast`

toast(
    title,
    message=None,
    *,
    kind='info',
    icon=None,
    on_dismiss=None,
    actions=(),
    width=340,
    progress=None,
    on_press=None,
    theme=None,
)

A notification.

Property	Default	Description
`title`	required	Title.
`message`	`None`	Secondary text.
`kind`	`"info"`	`"info"`, `"success"`, `"warning"` or `"error"`.
`icon`	`None`	Name of a Lucide icon (`pyzed icons` lists them).
`actions`	`()`	Extra widgets (usually buttons) shown as actions.
`width`	`340`	Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`progress`	`None`	0 to 1: a thin bar at the bottom (time left, a download).
`theme`	`None`	Theme to use instead of the current one (`pyzed.theme.current()`).

Events: on_dismiss, on_press (events).

Full reference →

`ui.toasts`

toasts(base, items, *, spacing=8)

Shows items (usually toast(...)) stacked in the bottom-right corner over base.

Property	Default	Description
`base`	required	The UI underneath.
`items`	required	List of toasts.
`spacing`	`8`	Space between children, in pixels.