Toast Service — Lumeo Documentation

Quick Start

The ToastService is registered automatically when you call AddLumeo() in your Program.cs. You only need to place a <ToastProvider /> in your layout and then inject the service wherever you need it.

1. Register services

// Program.cs
builder.Services.AddLumeo();   // registers ToastService (and all other Lumeo services)

2. Add the provider to your layout

Place <ToastProvider /> once in your MainLayout.razor. This is the container that renders all toast notifications.

<!-- MainLayout.razor -->
<div class="min-h-screen">
    @Body
    <ToastProvider Position="ToastViewport.ToastPosition.BottomRight"
                   DefaultDuration="5000"
                   MaxToasts="5" />
</div>

3. Inject and use

Inject ToastService into any component and call one of its methods to show a toast. Every method returns a string toast ID you can use to dismiss or update it later.

@inject ToastService ToastService

<Button OnClick="HandleSave">Save</Button>

@code {
    private void HandleSave()
    {
        ToastService.Success("Saved", "Your changes have been saved.");
    }
}

Variants

Five built-in variants cover the most common notification types. Each has a convenience method that sets the ToastVariant for you.

// Default — neutral notification
ToastService.Show("Event created", "Monday, January 1st at 5:00 PM");

// Success — operation completed
ToastService.Success("Saved", "Your profile has been updated.");

// Error (Destructive) — something went wrong
ToastService.Error("Error", "Could not connect to the server.");

// Warning — heads up
ToastService.Warning("Warning", "Your session will expire in 5 minutes.");

// Info — helpful tip
ToastService.Info("Tip", "You can drag items to reorder them.");

Click each button to see the variant in action:

With Options

For full control, pass a ToastOptions object. This lets you set action buttons, durations, dismiss behavior, callbacks, and custom CSS.

Action Button

Add an action button to the toast with ActionLabel and OnAction. Common use case: undo a destructive operation.

ToastService.Show(new ToastOptions
{
    Title = "Message archived",
    Description = "1 conversation moved to archive.",
    ActionLabel = "Undo",
    OnAction = () => RestoreMessage(),
    Duration = 8000
});

Non-dismissible (Persistent)

Set Dismissible = false to hide the close button and Duration = 0 to prevent auto-dismiss. The toast stays until you call Dismiss(id) or Update(id, ...) programmatically.

var id = ToastService.Show(new ToastOptions
{
    Title = "Processing payment...",
    Description = "Please do not close this page.",
    Variant = ToastVariant.Info,
    Dismissible = false,
    Duration = 0
});

// Later, dismiss it when the operation completes
ToastService.Dismiss(id);

Custom Duration

Override the default 5-second duration. Set any value in milliseconds, or 0 for no auto-dismiss.

// This toast stays visible for 10 seconds
ToastService.Show(new ToastOptions
{
    Title = "Deployment started",
    Description = "Building and deploying to production...",
    Variant = ToastVariant.Info,
    Duration = 10000
});

Custom CSS Class

Apply additional CSS classes to the toast element with the Class property.

ToastService.Show(new ToastOptions
{
    Title = "Styled toast",
    Description = "This toast has a custom border.",
    Class = "border-2 border-primary"
});

OnDismiss Callback

Run code when a toast is dismissed (by the user or by timeout) using the OnDismiss callback.

ToastService.Show(new ToastOptions
{
    Title = "Feedback requested",
    Description = "Rate your experience before this disappears.",
    OnDismiss = () => LogDismissal(),
    Duration = 6000
});

Dismiss & Update

Every Show() call returns a unique toast ID. Use it to dismiss or update that toast later.

Dismiss by ID

Store the ID returned by Show() and pass it to Dismiss(id) to remove a specific toast.

var id = ToastService.Show("Processing...", "This may take a moment.");

// Later...
ToastService.Dismiss(id);

Dismiss All

Clear every active toast at once. Useful when navigating away from a page or resetting state.

ToastService.DismissAll();

Update an Existing Toast

Change the title, description, variant, or any other property of an active toast. The toast stays in place and its timer resets.

var id = ToastService.Show("Connecting...", "Establishing connection.");

// After connection succeeds:
ToastService.Update(id, new ToastOptions
{
    Title = "Connected!",
    Description = "You are now online.",
    Variant = ToastVariant.Success,
    Duration = 3000
});

Real-world Pattern: Upload Progress

A common pattern: show a persistent loading toast, then update it to success or error when the operation completes.

var id = ToastService.Show(new ToastOptions
{
    Title = "Uploading file...",
    Description = "report-q4.pdf (2.3 MB)",
    Dismissible = false,
    Duration = 0     // stays until we update it
});

// Simulate upload completion after 3 seconds
await Task.Delay(3000);

ToastService.Update(id, new ToastOptions
{
    Title = "Upload complete!",
    Description = "report-q4.pdf uploaded successfully.",
    Variant = ToastVariant.Success,
    Dismissible = true,
    Duration = 4000
});

Promise Toast

The Promise<T> method wraps an async operation. It shows a loading toast, then automatically transitions to success or error based on the result. No manual ID tracking needed.

Async Success

The action returns a value, which you can use in the success toast options.

await ToastService.Promise(
    action: async () =>
    {
        await Http.PostAsync("/api/orders", content);
        return new { OrderId = 1042 };
    },
    loading: new ToastOptions
    {
        Title = "Placing order...",
        Description = "Processing your payment."
    },
    success: result => new ToastOptions
    {
        Title = "Order confirmed!",
        Description = $"Order #{result.OrderId} is on its way.",
        Variant = ToastVariant.Success,
        Duration = 5000
    },
    error: ex => new ToastOptions
    {
        Title = "Order failed",
        Description = ex.Message,
        Variant = ToastVariant.Destructive
    }
);

Async Error

If the action throws, the error callback receives the exception and displays a destructive toast.

await ToastService.Promise(
    action: async () =>
    {
        await Http.DeleteAsync("/api/resource/99");
        throw new HttpRequestException("403 Forbidden");
        return true;   // unreachable, needed for type inference
    },
    loading: new ToastOptions { Title = "Deleting resource..." },
    success: _ => new ToastOptions
    {
        Title = "Deleted",
        Variant = ToastVariant.Success
    },
    error: ex => new ToastOptions
    {
        Title = "Delete failed",
        Description = $"Server returned: {ex.Message}",
        Variant = ToastVariant.Destructive,
        Duration = 8000
    }
);

Custom Content

When the built-in title/description layout isn't enough, pass a RenderFragment as CustomContent to render arbitrary Razor markup inside the toast.

ToastService.Show(new ToastOptions
{
    CustomContent = @<div class="flex items-center gap-3">
        <Avatar Src="/img/user.jpg" Fallback="JD" Size="sm" />
        <div>
            <p class="font-medium text-sm">Jane Doe</p>
            <p class="text-xs text-muted-foreground">Sent you a message</p>
        </div>
    </div>,
    Duration = 6000
});

You can also use the Show(RenderFragment, variant?, duration?) overload for a shorter syntax:

ToastService.Show(
    @<Flex Gap="2" Align="center">
        <Badge Variant="Badge.BadgeVariant.Success">New</Badge>
        <span class="text-sm">Version 2.1 is available</span>
    </Flex>,
    variant: ToastVariant.Default,
    duration: 7000
);

Toast Positions

The ToastProvider accepts a Position parameter that determines where toasts appear on screen. This is set once in your layout and applies to all toasts.

Position	CSS Placement
TopLeft	Fixed to top-left corner
TopCenter	Fixed to top-center
TopRight	Fixed to top-right corner
BottomLeft	Fixed to bottom-left corner
BottomCenter	Fixed to bottom-center
BottomRight	Fixed to bottom-right corner (default)

<!-- Top-right positioning -->
<ToastProvider Position="ToastViewport.ToastPosition.TopRight" />

<!-- Bottom-center positioning -->
<ToastProvider Position="ToastViewport.ToastPosition.BottomCenter" />

Position is set on the ToastProvider in your layout, not on individual toasts. All toasts share the same position. If you need multiple positions, add multiple providers (not recommended).

API Reference

ToastService Methods

All Show methods return a string toast ID.

Method	Returns	Description
Show(title, description?, variant?)	string	Show a toast with a title, optional description, and optional variant.
Show(ToastOptions)	string	Show a toast with full control over all options.
Show(RenderFragment, variant?, duration?)	string	Show a toast with custom Razor content instead of title/description.
Success(title, description?)	string	Shorthand for `Show(title, description, ToastVariant.Success)`.
Error(title, description?)	string	Shorthand for `Show(title, description, ToastVariant.Destructive)`.
Warning(title, description?)	string	Shorthand for `Show(title, description, ToastVariant.Warning)`.
Info(title, description?)	string	Shorthand for `Show(title, description, ToastVariant.Info)`.
Dismiss(toastId)	void	Remove a specific toast by its ID.
DismissAll()	void	Remove all active toasts at once.
Update(toastId, ToastOptions)	void	Replace all options on an existing toast. Resets the auto-dismiss timer.
Promise<T>(action, loading, success, error)	Task<string>	Show a loading toast, run the async action, then update to success or error. Returns the toast ID.

ToastOptions Properties

Property	Type	Default	Description
Title	string?	null	The main heading text displayed in the toast.
Description	string?	null	Secondary text displayed below the title.
Variant	ToastVariant	Default	Visual style of the toast. Determines border and background color.
Duration	int?	null (uses provider default)	Auto-dismiss time in milliseconds. Set to `0` for no auto-dismiss. When null, falls back to the provider's `DefaultDuration`.
Dismissible	bool	true	Whether the close (X) button is rendered. Set to `false` for toasts that must be dismissed programmatically.
ActionLabel	string?	null	Text for an action button rendered inside the toast (e.g., "Undo", "Retry").
OnAction	Action?	null	Callback invoked when the action button is clicked.
OnDismiss	Action?	null	Callback invoked when the toast is dismissed (by user click or programmatically).
CustomContent	RenderFragment?	null	Custom Razor content that replaces the default title/description layout. When set, `Title` and `Description` are ignored.
Class	string?	null	Additional CSS classes appended to the toast element.

ToastVariant Enum

Value	Convenience Method	Description
Default	Show()	Neutral notification with card background and border.
Success	Success()	Green-tinted background indicating a successful operation.
Destructive	Error()	Red-tinted background indicating a failure or error.
Warning	Warning()	Amber/yellow-tinted background for cautionary messages.
Info	Info()	Blue-tinted background for informational messages and tips.

ToastProvider Parameters

Parameter	Type	Default	Description
Position	ToastViewport.ToastPosition	BottomRight	Screen position where toasts appear. One of: TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, BottomRight.
DefaultDuration	int	5000	Default auto-dismiss duration in milliseconds for toasts that don't specify their own `Duration`.
MaxToasts	int	5	Maximum number of toasts visible at once. When exceeded, the oldest non-persistent toast is evicted.