Toast

A short message that appears in the corner and goes away on its own.

Default
{var $url = $page->url()}

<div class="flex flex-wrap gap-2">
	{ui button,
		title: 'Save',
		variant: 'outline',
		attrs: [
			'hx-get' => "{$url}:toast?variant=success",
			'hx-swap' => 'none',
		],
	/}
	{ui button,
		title: 'Check for updates',
		variant: 'outline',
		attrs: [
			'hx-get' => "{$url}:toast?variant=info",
			'hx-swap' => 'none',
		],
	/}
	{ui button,
		title: 'Fail',
		variant: 'outline',
		attrs: [
			'hx-get' => "{$url}:toast?variant=destructive",
			'hx-swap' => 'none',
		],
	/}
</div>

A toast is a fragment the server adds to a fixed region of the layout, the same way a modal is filled in. The layout holds one <div id="toasts" class="toasts" role="status"></div>. Because the region is already on the page and is a live region, a screen reader announces each toast as it arrives.

A toast is usually the answer to an action, so any response can carry one. Wrap it in a fragment that targets the region and adds to the end of it:

{fragment 'toast', target: 'toasts', swap: 'beforeend'}
	{component toast,
		title: 'Saved',
		variant: 'success',
		icon: 'circle-check',
	/}
{else}
{/fragment}

The empty {else} keeps the toast out of a normal visit to the page. A POST handler that saves can return the same markup, so a form shows its result without a reload.

Timing and closing

The shared ui.js removes a toast after duration milliseconds, 5000 by default. duration: 0 keeps it until it is closed. The close button is always there, and several toasts stack in the order they arrive.

variant is success, warning, info or destructive. It colours the border and the icon, and the text stays the normal colour so it reads in both themes.

Params

Param Default Description
title null the bold first line
description null muted text under the title
variant null success, warning, info or destructive
icon null an icon name, before the text
duration 5000 milliseconds before ui.js removes it; 0 keeps it until closed
class '' added to toast
attrs [] any other attributes, e.g. ['id' => 'saved']