Toast

Overview

Toast is a succinct message that is displayed temporarily. It automatically closes on a timer that pauses on hover, focus, and window blur, then resumes; it supports swipe to dismiss and announces to assistive technology via polite or assertive live regions by toast Type. A toast can be manager-driven (via ToastManager) or manual (@bind-Open / DefaultOpen).

Anatomy

@using Navius.Primitives.Components.Toast
@inject ToastManager Toast

<NaviusToastProvider Manager="Toast">
    <NaviusToastViewport>
        @foreach (var t in Toast.Toasts)
        {
            <NaviusToastRoot Toast="t" @key="t.Id">
                <NaviusToastContent>
                    <NaviusToastTitle />
                    <NaviusToastDescription />
                    <NaviusToastAction />
                    <NaviusToastClose />
                </NaviusToastContent>
            </NaviusToastRoot>
        }
    </NaviusToastViewport>
</NaviusToastProvider>

Provider

Cascades configuration (duration, label, swipe) to every descendant toast and viewport, and owns the shared announcer. Renders no DOM of its own.

Prop	Type	Default	Description
Manager	ToastManager?	-	An externally-created manager. Falls back to the injected scoped one.
Limit	int	1	Max simultaneously-visible toasts; the rest queue (data-limited).
Timeout	int	5000	Default auto-close duration in ms for descendant toasts.
Label	string	"Notification"	Accessible label prefix announced for each toast.
SwipeDirection	string	"right"	Swipe gesture direction: right | left | up | down.
SwipeThreshold	double	50	Swipe distance in px required to dismiss.
ChildContent	RenderFragment?	-	The Viewport and its toasts.

Viewport

The fixed region that hosts the live toasts. Renders an ol with role="region", plus the visually-hidden live announcer regions.

Prop	Type	Default	Description
Hotkey	string[]	[ "F6" ]	Keyboard shortcut that focuses the viewport from anywhere.
LabelTemplate	Func<string, string, string>?	-	Template for the viewport’s accessible label: "{label} ({hotkey})" by default.
ChildContent	RenderFragment?	-	The toast Root elements.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered ol.

Root

A single toast. Owns the open lifecycle, the auto-close timer, and the swipe gesture. Renders an li.

Prop	Type	Default	Description
Toast	ToastObject?	-	The source toast when driven by a ToastManager; null for a manual toast.
Open	bool	true	Controlled open state (manual). Pair with OpenChanged (@bind-Open).
OpenChanged	EventCallback<bool>	-	Fires when the controlled Open value should change.
DefaultOpen	bool	true	Initial open state when used uncontrolled (manual).
ForceMount	bool	false	Keeps the toast mounted while closed, for CSS-driven presence.
Timeout	int?	-	Per-toast auto-close override (ms). null falls back to Toast.Timeout, then Provider.Timeout; 0 is sticky.
Priority	string	"low"	Announcement urgency: low (role="status", polite) or high (role="alert", assertive).
Type	string?	-	Visual/semantic type (success | error | loading). Defaults to Toast.Type; drives data-type.
SwipeDirection	string?	-	Per-toast swipe direction override; falls back to the Provider default.
OnEscapeKeyDown	EventCallback<NaviusEscapeKeyDownEventArgs>	-	Fires on Escape; cancelable.
OnSwipeStart	EventCallback	-	Fires when a swipe gesture begins.
OnSwipeMove	EventCallback<(double X, double Y)>	-	Fires as the swipe moves.
OnSwipeEnd	EventCallback<(double X, double Y)>	-	Fires when the swipe ends (dismiss or snap-back).
OnSwipeCancel	EventCallback	-	Fires when the swipe gesture is cancelled.
OnPause	EventCallback	-	Fires when the auto-close timer pauses.
OnResume	EventCallback	-	Fires when the auto-close timer resumes.
ChildContent	RenderFragment?	-	The Content wrapper.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered li.

During a swipe the engine writes --toast-swipe-movement-x and --toast-swipe-movement-y (px) on the root so CSS transforms can follow the pointer.

Content

The stacking element between Root and Title/Description/Action/Close. Carries the C#-computed stacking CSS variables. Renders a div.

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	The Title, Description, Action, and Close parts.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

While stacked the engine writes --toast-index, --toast-height, --toast-offset-y, and --toast-frontmost-height on the element so CSS can compute the collapsed-overlap vs. expanded-fan-out transforms.

Title

The toast’s title. Carries the id referenced by the Root’s aria-labelledby. Renders a div.

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	Title content. Falls back to Toast.Title when omitted.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Description

The toast’s description. Carries the id referenced by the Root’s aria-describedby. Renders a div.

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	Description content. Falls back to Toast.Description when omitted.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Action

An actionable button inside a toast (e.g. Undo). Activating it closes the toast. AltText is required for assistive tech. Renders a button.

Prop	Type	Default	Description
AltText	string	""	A plain-text description of the action, for assistive tech and as the alternative way to perform it.
OnClick	EventCallback	-	Consumer click handler, invoked before the toast closes.
ChildContent	RenderFragment?	-	Action label content. Falls back to the manager action’s label when omitted.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Close

A composable close button that dismisses the toast on click. Renders a button.

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	Close button content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Data attributes

Part	Attribute	Description
Viewport	data-navius-toast-viewport	Present on the viewport region.
Viewport	data-expanded	Present while the stack is expanded (hover/focus-within).
Root	data-open	Present while the toast is open.
Root	data-closed	Present while the toast is closed.
Root	data-expanded	Present while the stack is expanded, mirrored from the Viewport.
Root	data-type	The toast’s Type, when set.
Root	data-swipe-direction	"right" | "left" | "up" | "down"
Root	data-swiping	Present during a swipe.
Root	data-limited	Present while queued beyond the visible limit.
Content	data-behind	Present when a later toast is stacked in front of this one.
Content	data-expanded	Present while the stack is expanded, mirrored from the Viewport.
Title	data-navius-toast-title	Present on the title element.
Description	data-navius-toast-description	Present on the description element.
Action	data-navius-toast-action	Present on the action button.
Close	data-navius-toast-close	Present on the close button.

Keyboard interactions

Key	Behavior
F6	Moves focus to the viewport, so the toasts and their buttons can be reached. Configurable via Hotkey.
Tab	Moves focus through the focusable elements inside the focused toast (its action and close buttons).
Space	When focus is on an Action or Close button, activates it and dismisses the toast.
Enter	When focus is on an Action or Close button, activates it and dismisses the toast.
Escape	Closes the focused toast, unless prevented in OnEscapeKeyDown.

ARIA mechanism

A foreground toast (Priority="high") renders role="alert" (assertive); a background toast (Priority="low", the default) renders role="status" (polite). Title and Description supply aria-labelledby and aria-describedby on the Root. This implements the WAI-ARIA APG alert pattern and is covered by the Playwright browser test suite and gated by axe-core in CI.