Toast
Displays a temporary notification popup message.
Installation
dotnet add package Lumeo
One-time app setup (AddLumeo(), CSS & JS) is covered in the
installation guide.
Usage
@using Lumeo <Toast />
When to Use
- Show non-blocking notifications that do not interrupt the user's workflow.
- Confirm the result of an action such as saving, copying, or deleting.
- Display async operation results like API responses or background task completions.
Pick a variant then show a toast to see it applied live.
Pick a position then click Show to see where the toast appears.
Fire a few toasts, then let them sit — the newest sits in front at full scale while older ones collapse behind it with a small offset and a scale step down. Hover the stack (or Tab into it) to fan it back out to the full list; move away or Tab out and it collapses again.
Stacking is on by default. When more than one toast is visible in a position group, all
but the newest collapse behind it (small offset, scaled down, capped at 3 visible). Hovering the group —
or moving keyboard focus into it — expands it back to the full list; leaving collapses it again. Set
StackToasts="false" on
ToastProvider to always render the
plain list instead.
Mobile (rc.49). The dismiss button is now always visible and 44×44 px on small screens (
opacity-100 sm:opacity-0 sm:group-hover:opacity-100), meeting the WCAG touch-target minimum without requiring a hover.
Hover/focus pauses auto-dismiss. Toasts pause their auto-dismiss timer while the toast is hovered
or any element inside it has focus, then resume on leave / blur. Users get the full reading window even on a
short
Duration, and keyboard users can tab
to an action without the toast vanishing under them.
Variant-aware ARIA role.
Destructive
toasts render as role="alert" with
aria-live="assertive" so screen readers
interrupt and announce errors immediately. All other variants render as
role="status" with
aria-live="polite", queuing alongside the
current speech rather than cutting in.
Parameter Coverage
Every ToastVariant rendered statically (without going through ToastService).
ToastVariant
Default
Default
Static preview of the Default toast variant.
Success
Success
Static preview of the Success toast variant.
Destructive
Destructive
Static preview of the Destructive toast variant.
Warning
Warning
Static preview of the Warning toast variant.
Info
Info
Static preview of the Info toast variant.
API Reference
Toast
| Property | Type | Default | Description |
|---|---|---|---|
| Variant | ToastVariant | Default | Visual style of the toast. Values: Default, Success, Destructive, Warning, Info. |
| Id | string? | null | Stable DOM id for the toast root. Set by ToastProvider so it can register the swipe-to-dismiss gesture against this element. |
| OnMouseEnter | EventCallback | — | Invoked when the pointer enters the toast. ToastProvider uses this to pause the auto-dismiss timer. |
| OnMouseLeave | EventCallback | — | Invoked when the pointer leaves the toast. ToastProvider uses this to resume the auto-dismiss timer. |
| OnFocusIn | EventCallback | — | Invoked when focus enters the toast or an element inside it. ToastProvider uses this to pause the auto-dismiss timer. |
| OnFocusOut | EventCallback | — | Invoked when focus leaves the toast and its contents. ToastProvider uses this to resume the auto-dismiss timer. |
| StackIndex | int? | null | Position of this toast within a collapsed stack (0 = frontmost). Set by ToastViewport when StackToasts is enabled; null renders the toast as a plain list item. |
| Leaving | bool | false | Set by ToastProvider while the exit animation plays, so the toast can apply its leaving transition before being removed from the DOM. |
ToastOptions
| Property | Type | Default | Description |
|---|---|---|---|
| Title | string | — | The main heading text of the toast. |
| Description | string? | null | Optional secondary text displayed below the title. |
| Duration | int | 5000 | Auto-dismiss duration in milliseconds. Set to 0 to disable auto-dismiss. |
| Dismissible | bool | true | Whether the toast can be manually dismissed by the user. |
| ActionLabel | string? | null | Label text for the optional action button. |
| OnAction | Action? | null | Callback invoked when the action button is clicked. |
| Position | ToastPosition? | null | Per-toast position override. When null the toast inherits the position from the ToastProvider. |
| Variant | ToastVariant | Default | Visual style. Values: Default, Success, Destructive, Warning, Info. |
ToastService
| Method | Signature | Description |
|---|---|---|
| Show | Show(title, description?) | Shows a default toast with optional description. |
| Show | Show(ToastOptions) | Shows a toast with full options including action button and duration. |
| Success | Success(title, description?) | Shows a success-styled toast. |
| Error | Error(title, description?) | Shows a destructive-styled error toast. |
| Promise | Promise(task, loading, success, error) | Shows loading state while the async task runs, then transitions to success or error. |
ToastProvider
| Property | Type | Default | Description |
|---|---|---|---|
| Position | ToastPosition | BottomRight | Viewport corner the toasts stack in. Values: TopLeft, TopRight, TopCenter, BottomLeft, BottomRight, BottomCenter. |
| DefaultDuration | int | 4000 | Default lifetime for toasts in milliseconds when Duration is not specified. |
| MaxToasts | int | 5 | Maximum number of toasts shown at once; older toasts are dismissed. |
| MaxVisible | int | 0 | Caps the number of simultaneously displayed toasts by syncing MaxToasts when greater than 0. 0 = unlimited. Older toasts are evicted and resurface when newer ones are dismissed. |
| StackToasts | bool | true | Sonner-style stacking. When a position group holds more than one toast, older toasts collapse behind the newest (small offset, scaled down, at most 3 visible); hovering the group or moving keyboard focus into it expands it to the full list. Set false to always render the plain list. |
ToastViewport
Internal per-position-group container rendered by ToastProvider for each occupied corner; not typically used directly.
| Property | Type | Default | Description |
|---|---|---|---|
| Position | ToastPosition | BottomRight | Viewport corner this group renders in. Set by ToastProvider. |
| StackToasts | bool | true | Whether the provider wants sonner-style stacking for this group. |
| ToastCount | int | 0 | Number of toasts currently rendered in this position group (including collapsed ones). Set by ToastProvider. |
| OnExpandedChanged | EventCallback<bool> | — | Fires whenever the stack's expanded state flips (hover-enter/leave, keyboard focus in/out). |
ToastAction / ToastClose
| Property | Type | Default | Description |
|---|---|---|---|
| Label | string? | null | ToastAction — button text. |
| OnClick | EventCallback | — | ToastAction — invoked when the action button is clicked. |
| OnClose | EventCallback | — | ToastClose — invoked when the close button dismisses the toast. |
| AriaLabel | string? | null | ToastClose — accessible name for the close button, overriding the localized default. Use for i18n. |