Notification

Support and permission

IsSupported / GetPermission / RequestPermission

IsSupported reports whether the runtime implements the Notifications API at all. GetPermission reads the current decision without prompting, while RequestPermission shows the browser's permission dialog and resolves with the user's choice: Granted, Denied or Default.

@inject Bit.Butil.Notification notification

var isSupported = await notification.IsSupported();

var current = await notification.GetPermission();

var granted = await notification.RequestPermission(); // shows the browser prompt

Live sample

Current permission: unknown

permission output

Results will appear here when you interact with the samples.

Show a notification

Show

Displays a fire-and-forget system notification. NotificationOptions maps the full option surface of the Notification constructor: Body, Icon, Image, Badge, Tag, Lang, Dir, Renotify, RequireInteraction, Silent, Timestamp, Vibrate and arbitrary Data. Reusing the same Tag replaces the previous toast instead of stacking a new one.

await notification.Show("Deploy finished", new()
{
    Body = "All 12 services rolled out successfully.",
    Icon = "https://example.com/icon.png",
    Tag = "deploy-status",       // same tag replaces the previous toast
    RequireInteraction = false,  // auto-dismiss per OS rules
    Silent = false,
});

Live sample

Title

Tag (optional)

Body

Icon URL (optional)

RequireInteraction Silent

show output

Results will appear here when you interact with the samples.

Tracked notifications with callbacks

ShowTracked

ShowTracked returns a NotificationHandle and wires C# callbacks to the notification's click, show, close and error events. The handle lets you close the toast programmatically; disposing it detaches the listeners. Tracked notifications stay on screen until dismissed or closed.

var handle = await notification.ShowTracked("Incoming call",
    new() { Body = "Click to answer." },
    onClick: () => { /* focus the call UI */ },
    onShow: () => { /* start the ringtone */ },
    onClose: () => { /* stop the ringtone */ },
    onError: () => { /* fall back to in-app banner */ });

// later:
await handle.Close();
await handle.DisposeAsync();

Live sample

tracked output

Results will appear here when you interact with the samples.

Permission prompts need a user gesture Browsers only show the notification permission dialog in response to a user interaction, and many deny it outright in cross-origin iframes or on insecure origins. Request permission from a click handler - like the button above - never on page load.

The OS has the final say Even with permission granted, the operating system can suppress toasts: Windows Focus Assist, macOS Focus modes and Do Not Disturb all silently swallow notifications. Treat them as best-effort UX, not a delivery guarantee.

API reference

Member

Signature

Description

IsSupported

ValueTask<bool> IsSupported()

Checks if the runtime (browser or web-view) supports the Web Notification API.

GetPermission

ValueTask<NotificationPermission> GetPermission()

Gets the current permission of the Notification API without prompting.

RequestPermission

ValueTask<NotificationPermission> RequestPermission()

Requests permission from the user for the current origin to display notifications.

Show

ValueTask Show(string title, NotificationOptions? options = null)

Requests a native notification to show to the user.

ShowTracked

ValueTask<NotificationHandle> ShowTracked(string title, NotificationOptions? options = null, Action? onClick = null, Action? onShow = null, Action? onClose = null, Action? onError = null)

Shows a notification and returns a handle with click / show / close / error callbacks and programmatic close.

DisposeAsync

ValueTask DisposeAsync()

Detaches all tracked notifications and releases the interop reference; called automatically when the scoped service is disposed.

NotificationHandle.Id

Guid Id

The internal notification id.

NotificationHandle.Close

ValueTask Close()

Closes the notification programmatically.

NotificationHandle.DisposeAsync

ValueTask DisposeAsync()

Detaches the event listeners and closes the toast.

InvokeNotificationClick / Show / Close / Error

void InvokeNotification…(Guid id)

JSInvokable interop plumbing dispatched from the Butil script - not intended for app code.