RzToastProvider

Installation / Root Layout Placement

In an application, place one provider near the root layout, typically after @Body. The provider renders all supported stacks up front; Position only controls the default stack for requests that do not provide a position.

@inherits LayoutComponentBase

<div class="min-h-screen">
    @Body
</div>

<RzToastProvider />

<RzToastProvider Id="docs-toast-provider"
                 Position="ToastPosition.TopRight"
                 MaxVisible="5"
                 ShowProgress="true" />

Server-triggered toasts with Rizzy

AddRizzyUI() registers the scoped IRzToastService and the internal ordered command queue. Add UseRzToast() to the request pipeline so commands queued during an HTMX request are emitted as one rz:toast:batch HX-Trigger event. The root layout must still render one RzToastProvider; the service only transports commands to the existing browser runtime.

builder.Services.AddRizzy();
builder.Services.AddRizzyUI();

var app = builder.Build();

app.UseRizzy();
app.UseRzToast();

app.MapControllers();
app.MapRazorComponents<App>();

The C# API mirrors the server-compatible Rizzy.toast methods: Show, Custom, Success, Error, Warning, Info, Loading, Update, Dismiss, and Clear. Commands keep their insertion order in the batch, so a show followed by an update for the same stable id is processed in that order by the browser.

public IActionResult Save([FromServices] IRzToastService toastService)
{
    toastService.Success("Project settings saved.", "Saved");
    return View();
}

Rizzy.toast.success("Project settings saved.", "Saved");

toastService.Show(new RzToastMessage
{
    Status = ToastStatus.Warning,
    Title = "Session expiring",
    Text = "Your session expires in two minutes.",
    Position = ToastPosition.BottomRight,
    Duration = 7000,
    DedupeKey = "session-expiration"
});

var handle = toastService.Loading("Uploading file...", "Uploading", new RzToastOptions
{
    Id = "profile-photo-upload"
});

handle.Update(new RzToastUpdate
{
    Status = ToastStatus.Success,
    Title = "Uploaded",
    Text = "Your profile photo was updated.",
    AutoClose = true,
    Duration = 3000,
    Progress = true
});

toastService.Update("profile-photo-upload", new RzToastUpdate
{
    Status = ToastStatus.Success,
    Title = "Uploaded",
    Text = "Your profile photo was updated."
});

toastService.Dismiss("obsolete-toast");
toastService.Dismiss();
toastService.Clear();

toastService.Success("Message archived.", "Archived", new RzToastOptions
{
    Action = new RzToastAction
    {
        Label = "Undo",
        EventName = "rz:message:restore",
        Detail = new { MessageId = 42 }
    }
});

Live Examples

These examples use delegated documentation event listeners and stable data-rz-toast-demo attributes. The buttons call the real Rizzy.toast facade in the same DOM context as the provider above.

Rizzy.toast.show({
    title: "Notification",
    description: "The background check completed."
});

Rizzy.toast.info("The report is being generated. You can continue working.", "Report started");

Rizzy.toast.success("Project settings saved.", "Saved");

Rizzy.toast.info("Build started. You can continue working while it runs.", "Build started");

Rizzy.toast.warning("Your session expires in 2 minutes.", "Session expiring");

Rizzy.toast.error("Unable to upload image. Check the file type and try again.", "Upload failed");

Rizzy.toast.success("Message archived.", "Archived", {
    action: {
        label: "Undo",
        dismissOnClick: true,
        onClick: toast => {
            Rizzy.toast.info("The message was restored.", "Undo complete");
            toast.dismiss();
        }
    }
});

Rizzy.toast.info("Waiting for the background worker to respond.", "Still working", {
    autoclose: false,
    progress: false
});

Rizzy.toast.success("Export completed and is ready to download.", "Export ready", {
    duration: 7000
});

Rizzy.toast.loading("Uploading changes...", "Syncing", {
    id: "docs-loading-demo"
});

setTimeout(() => {
    Rizzy.toast.update("docs-loading-demo", {
        status: "success",
        title: "Synced",
        text: "All changes are online.",
        autoclose: true,
        duration: 3000,
        progress: true
    });
}, 1500);

Rizzy.toast.info("This toast appears in the top-right stack.", "Top right", {
    position: "top-right"
});

Rizzy.toast.info("This toast uses the Simple Notify alias bottom left.", "Bottom left", {
    position: "bottom left"
});

Rizzy.toast.info("This toast appears in the center stack.", "Center", {
    position: "center"
});

Rizzy.toast.info("This toast uses the Simple Notify alias right y-center.", "Right center", {
    position: "right y-center"
});

Rizzy.toast.info("This toast can be dismissed by id.", "Tracked toast", {
    id: "docs-dismiss-demo",
    autoclose: false,
    progress: false
});

Rizzy.toast.dismiss("docs-dismiss-demo");

Rizzy.toast.clear();

window.dispatchEvent(new CustomEvent("rz:toast", {
    detail: {
        id: "docs-event-demo",
        status: "success",
        title: "Saved",
        description: "The event API created this toast."
    }
}));

window.dispatchEvent(new CustomEvent("rz:toast:update", {
    detail: {
        id: "docs-event-demo",
        text: "The event API updated this toast."
    }
}));

window.dispatchEvent(new CustomEvent("rz:toast:dismiss", {
    detail: { id: "docs-event-demo" }
}));

window.dispatchEvent(new CustomEvent("rz:toast:clear"));

Rizzy.toast.show({
    dedupeKey: "docs-storage-warning",
    status: "warning",
    title: "Storage warning",
    text: "Storage is still almost full.",
    incrementCount: true
});

for (let index = 1; index <= 7; index += 1) {
    Rizzy.toast.info(`Stacked notification ${index}`, "Stack demo", {
        position: "bottom-right",
        duration: 8000
    });
}

Usage Guidelines

Use RzAlert for persistent inline feedback, a dialog for required decisions, and form validation messages near the related field.

API Reference

Provider Parameters

Toast Request Options

Statuses

Positions

Overflow Strategies

Accessibility

Toasts do not steal focus. The provider root exposes a named region, while each JavaScript-rendered toast announces through live-region semantics instead of moving the user away from their current task.

Default, info, success, warning, and loading toasts use role="status" with aria-live="polite". Error toasts use role="alert" with aria-live="assertive". Every toast uses aria-atomic="true" so assistive technology announces the complete message.

Close controls are native buttons with accessible labels, action buttons are keyboard reachable, and Escape can dismiss a focused toast when CloseOnEscape is enabled. Auto-dismiss timers pause on hover and focus when configured, helping users read or act on content before it disappears.

Give users enough time for toast content, avoid long or critical messages, and never make a toast the only way critical information is communicated. Reduced-motion preferences are respected through the generated class map, and functional timing does not depend on animation.

Theming

Provider and toast item classes come from Theme.RzToastProvider. JavaScript reads the class map rendered by the provider and applies slot, status, tone, animation, state, and position classes without constructing Tailwind class strings at runtime.

Override the descriptor in your theme to adjust the provider root, viewport stacks, toast item slots, status variants, tones, animations, and reduced-motion-safe states.

CSP Notes

The toast runtime is loaded through the normal RizzyUI JavaScript entries, including the CSP-safe entry. It avoids eval, new Function, inline event handlers, dynamic script injection, and runtime Tailwind construction.

This documentation page uses a CSP-safe delegated listener in /js/site.js. Toast text is assigned as text content by the runtime; HTML content must be supplied as a trusted HTMLElement.

Migration Notes

The public Rizzy.toast facade preserves compatibility helpers such as success, error, warning, info, custom, and Simple Notify option aliases including variant, message, description, autotimeout, effect, type, customClass, and compatible position strings.

Simple Notify CSS class names are not preserved. Style toast output through Theme.RzToastProvider and the provider-generated class map.

Troubleshooting