Toast

A notification toast widget that displays temporary messages.

Toast notifications appear in a small window, typically in the corner of the screen, and can display a title, message, icon, buttons, and optional metadata. They can be configured to auto-dismiss after a duration or remain visible until manually closed.

init

__init__(
    *,
    title: Optional[str] = None,
    icon: Union[str, IconSpec, None] = None,
    message: Optional[str] = None,
    memo: Optional[str] = None,
    duration: Optional[int] = None,
    buttons: Optional[Sequence[dict[str, Any]]] = None,
    show_close_button: bool = True,
    accent: Optional[str] = None,
    bootstyle: Optional[str] = None,
    position: Optional[str] = None,
    alert: bool = False,
    on_dismissed: Optional[Callable[[Any], Any]] = None,
) -> None

Initialize a Toast notification.

Parameters:

Name	Type	Description	Default
`title`	`str`	The toast title text. If provided without a message, it will be displayed with a larger "label" font. If both title and message are provided, the title appears in the header and the message appears in a separate section below.	`None`
`icon`	`str \| dict`	Icon to display in the header. Can be a string icon name (e.g., "bootstrap-fill") or an IconSpec dict with name, size, and color properties.	`None`
`message`	`str`	The main message text. If no title is provided, this message is displayed in the header with a "body" font. If a title is provided, this appears in a separate section below the header.	`None`
`memo`	`str`	Small metadata text displayed in the header (e.g., "5 mins ago"). Appears with muted styling.	`None`
`duration`	`int`	Auto-dismiss duration in milliseconds. If None, the toast remains visible until manually closed.	`None`
`buttons`	`list`	Sequence of button configurations. Each dict can contain any bootstack button options (text, bootstyle, command, etc.). Button commands will trigger the on_dismissed callback before closing the toast.	`None`
`show_close_button`	`bool`	Whether to show the close button in the header. Default is True.	`True`
`accent`	`str`	Accent token for the toast container (e.g., "primary", "success", "danger"). If None, uses the default background color.	`None`
`bootstyle`	`str`	DEPRECATED - Use `accent` instead.	`None`
`position`	`str`	Tkinter geometry string for toast position (e.g., "-25-75" for bottom-right). If None, uses platform-specific defaults.	`None`
`alert`	`bool`	If True, plays a system bell sound when the toast is shown.	`False`
`on_dismissed`	`Callable`	Callback function invoked when the toast is dismissed. Receives the button options dict if dismissed via a button, or None if dismissed via close button or auto-dismiss.	`None`

setitem

__setitem__(key: str, value: Any) -> None

Set a configuration option using dictionary syntax.

getitem

__getitem__(key: str) -> Any

Get a configuration option using dictionary syntax.

configure

configure(
    option: Optional[str] = None,
    **kwargs: Unpack[ToastConfig],
) -> Optional[tuple[str, str, str, None, Any]]

Configure toast options.

Parameters:

Name	Type	Description	Default
`option`	`Optional[str]`	If provided, returns the configuration for this option.	`None`
`**kwargs`	`Unpack[ToastConfig]`	Configuration options to set.	`{}`

Returns:

Type	Description
`Optional[tuple[str, str, str, None, Any]]`	Configuration tuple if option provided, otherwise None.

cget

cget(option: str) -> Any

Get the value of a configuration option.

Parameters:

Name	Type	Description	Default
`option`	`str`	The configuration option name.	required

Returns:

Type	Description
`Any`	The value of the configuration option.

show

show(
    merge: bool = True, **options: Unpack[ToastConfig]
) -> None

Display the toast.

If options are provided, they are merged with the existing toast configuration. If you do not want this behavior, set the merge flag to False, or create a new toast instance.

Parameters:

Name	Type	Description	Default
`merge`	`bool`	If True, merge options with existing configuration. If False, clear existing options first.	`True`
`**options`	`Unpack[ToastConfig]`	Configuration options to set before showing.	`{}`

hide

hide() -> None

Hide the toast and trigger the on_dismissed callback.

destroy

destroy() -> None

Destroy the toast widget and cleanup resources.