Toast

Example

<section data-slean="toast" popover="manual" aria-label="Notifications">
	<ol data-slean-part="list" aria-live="polite"></ol>
</section>
<!-- showToast() adds, for each toast: -->
<li data-slean-part="item" data-variant="success">
	<p data-slean-part="title">Invoice sent</p>
	<p data-slean-part="description">harbor.studio receives it in a minute.</p>
	<button type="button" data-slean-part="action" data-slean-value="undo">Undo</button>
	<button type="button" data-slean-part="close" aria-label="Dismiss"></button>
</li>

<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static data-slean="toast".
	import '@svelte-lean/styles/toast.css';
	import { showToast, type ToastActionDetail } from '@svelte-lean/primitives/toast';
	import { on } from 'svelte/events';

	let region: HTMLElement;

	function sent() {
		showToast(region, {
			title: 'Invoice sent',
			description: 'harbor.studio receives it in a minute.',
			tone: 'success',
			action: { label: 'Undo', value: 'undo' }
		});
	}
</script>

<button type="button" onclick={sent}>Send invoice</button>

<section
	bind:this={region}
	data-slean="toast"
	popover="manual"
	aria-label="Notifications"
	{@attach (node) =>
		on(node, 'slean:action', (event) => {
			console.log((event as CustomEvent<ToastActionDetail>).detail.value);
		})}
>
	<ol data-slean-part="list" aria-live="polite"></ol>
</section>

Why this implementation exists

A toast has to render above everything, including an open dialog, without being closed by a click elsewhere, and a screen reader has to hear it without focus moving. popover="manual" gives the first: the top layer, no light dismiss. aria-live="polite" on the list gives the second.

What remains is time: each toast leaves after its duration, and the reader must be able to stop the clock (WCAG 2.2.1). That is ephemeral memory per toast, which is what Tier 2 is for. The timer lives in a WeakMap entry created by showToast() and deleted when the toast goes; pointer or focus in the region pauses every timer and leaving resumes them with the time that was left.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="toast"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/toast/register';

import '@svelte-lean/styles/toast.css';

Render one empty region per page, usually in the root layout, and keep a reference to it. Call showToast(region, options) with a title, and optionally a description, a tone (success, warning, danger), a duration in milliseconds (0 keeps it) and one action.

Listen to slean:action on the region for the action button’s value and to slean:dismiss to know why a toast left; cancelling a dismissal keeps the toast.

<script lang="ts">
	import type { ToastDismissDetail } from '@svelte-lean/primitives/toast';
	import { on } from 'svelte/events';

	// Keep an error until it has been read: cancel the timeout, allow the close button.
	function dismiss(event: Event) {
		const { item, reason } = (event as CustomEvent<ToastDismissDetail>).detail;
		if (reason === 'timeout' && item.dataset.variant === 'danger') event.preventDefault();
	}
</script>

<section
	data-slean="toast"
	popover="manual"
	aria-label="Notifications"
	{@attach (node) => on(node, 'slean:dismiss', dismiss)}
>
	<ol data-slean-part="list" aria-live="polite"></ol>
</section>

Anatomy

Runtime profile

The toast registers five handlers (click, pointerover, pointerout, focusin, focusout) with the shared router. Its per-instance state is one timer entry per visible toast; showing fifty toasts adds no listener (tests/toast.test.ts).

Accessibility contract

• The list is aria-live="polite": a new toast is announced after the current speech, and focus never moves.
• The region is shown one frame before the first toast is added, so the live region exists before its content changes.
• Hover or focus inside the region pauses every timer (WCAG 2.2.1); a toast with duration 0 stays until closed.
• The close button is named “Dismiss” (closeLabel changes it); the action is a native button with its label.
• For errors that must interrupt, use a second region whose list has role="alert".

Keyboard

Platform features

Without JavaScript

No toasts. Feedback that must survive without JavaScript belongs in the page, rendered by the server (the Alert primitive).

Server rendering

Render the empty region. showToast() is a browser call; nothing is created on the server.

Before hydration

Before the behavior loads there is nothing to show; the region is empty and closed.

Styling

toast.css places the region in one of six positions (data-slean-position), stacks the toasts, tints them from the soft tokens by tone, draws the close cross with borders and slides a new toast in. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :hover.

Variant attributes: data-variant (success, warning, danger).

Compatibility notes

The Popover API is Baseline 2024. Without it the region renders in place at its position, and toasts are still added, timed and announced.

Testing

• packages/primitives/tests/toast.test.ts Vitest: creation, timers, pause and resume, close, action, cancelable dismissal
• apps/playground/tests/primitives/widgets.spec.ts Playwright: tooltip, toast, tree, range slider and number field in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/toast/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/toast/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/toast/behavior.ts the behavior definition
• packages/primitives/src/toast/register.ts the registration module
• packages/styles/css/toast.css the optional stylesheet