Native Desktop Notification API for WebviewJS Apps

WebviewJS exposes a native desktop notification API that mirrors the familiar browser Notification interface. Under the hood it uses notify-rust, which delegates to each platform’s native notification system — macOS User Notifications, Windows Toast, or Linux/XDG D-Bus. Because WebviewJS runs as a native application rather than a sandboxed browser page, permission is always granted and requestPermission() is a no-op compatibility stub. Notifications can carry action buttons, inline images, and rich lifecycle event callbacks.

Android and iOS expose the full JavaScript Notification API for source compatibility, but do not display a notification or emit native lifecycle events on those platforms.

Permissions

import { Notification } from '@webviewjs/webview';

console.log(Notification.permission); // "granted" — always
await Notification.requestPermission(); // "granted" — never prompts

Notification.permission is always "granted" for native desktop applications. requestPermission() exists solely for code that was written against the browser Web Notification API and returns immediately without prompting the user.

Constructor

new Notification(title: string, options?: NotificationOptions)

title

string

required

The heading text displayed prominently at the top of the notification.

options

NotificationOptions

Optional configuration for the notification body, icon, actions, and behaviour.

Show NotificationOptions fields

body

string

Secondary text shown below the title.

icon

string

Platform icon name (e.g. "dialog-information" on Linux) or an absolute file path to an image.

image

string | Buffer

A richer inline image for the notification. Accepts a local file path string or a Buffer containing encoded image data (PNG, JPEG, WebP, GIF, BMP, ICO, TIFF, and other formats supported by the Rust image crate). Remote URLs are not fetched automatically — fetch them into a Buffer first.On Linux the decoded pixels are sent directly to the notification server. On Windows and macOS a temporary PNG file is written and removed with the notification lifecycle.

badge

string

URL or path of a small badge icon. Retained as a readonly property; not currently mapped to a native backend feature.

tag

string

Grouping tag for deduplication. Retained as a readonly property for API compatibility.

data

unknown

Arbitrary application data attached to the notification. Not sent to the OS.

dir

"auto" | "ltr" | "rtl"

Text direction. Defaults to "auto". Retained for API compatibility; not currently mapped to a native feature.

lang

string

BCP 47 language tag. Retained for API compatibility.

renotify

boolean

Whether to alert the user again when a notification with the same tag is replaced. Retained for API compatibility.

requireInteraction

boolean

When true, the notification stays on screen until the user explicitly interacts with it rather than auto-dismissing.

persistent

boolean

When true, the Node.js process is kept alive until the native backend reports an interaction or closure. Required when providing actions. Defaults to false.

actions

NotificationAction[]

Array of action buttons. Requires persistent: true — passing actions without it throws a TypeError.

Show NotificationAction fields

action

string

required

Machine-readable action identifier emitted in the click event payload.

title

string

required

Human-readable button label.

icon

string

Icon for the action button. Stored as readonly data; notify-rust does not currently expose per-action icons to the native backend.

silent

boolean

Suppress the notification sound. Retained for API compatibility.

timestamp

number

Unix timestamp (milliseconds) representing when the event occurred. Retained for API compatibility.

vibrate

number | number[]

Vibration pattern in milliseconds. Retained for API compatibility; not mapped to native desktop behaviour.

A non-empty actions array requires persistent: true. Without it the constructor throws a TypeError. On platforms where notify-rust cannot close a notification programmatically, calling close() will not release the persistent keep-alive.

Static Members

`Notification.permission`

permission

"granted"

Always "granted" — native applications are never subject to browser permission gates.

`Notification.requestPermission()`

returns

Promise<"granted">

Resolves immediately with "granted". Provided for compatibility with browser-targeted code.

Instance Properties (readonly)

All constructor options are preserved as readonly instance properties.

Property	Type	Description
`title`	`string`	Notification heading
`body`	`string`	Body text
`icon`	`string`	Icon path or platform name
`image`	`string \| Buffer`	Inline image
`badge`	`string`	Badge icon
`tag`	`string`	Grouping tag
`data`	`unknown`	Application-defined data
`dir`	`"auto" \| "ltr" \| "rtl"`	Text direction
`lang`	`string`	Language tag
`renotify`	`boolean`	Re-alert on same tag
`requireInteraction`	`boolean`	Persist until interaction
`persistent`	`boolean`	Keep process alive
`actions`	`NotificationAction[]`	Action buttons
`silent`	`boolean`	Suppress sound
`timestamp`	`number`	Event timestamp (ms)
`vibrate`	`number \| number[]`	Vibration pattern

Event Handler Properties

Assign functions directly for a familiar DOM-style interface:

notification.onclick  = (event) => { /* ... */ };
notification.onclose  = (event) => { /* ... */ };
notification.onerror  = (event) => { /* ... */ };
notification.onshow   = (event) => { /* ... */ };

Methods

`close()`

Programmatically dismisses the notification where the platform supports it. Currently available through the Linux/XDG backend via notify-rust. On Windows and macOS the call is safe but performs no native close operation.

`on(event, listener)`

event

NotificationEventName

required

One of "click", "close", "error", or "show".

listener

(event: NotificationEvent) => void

required

Callback invoked when the event fires.

returns

this

The Notification instance, for chaining.

Events

Notification implements TypedEventEmitter<NotificationEventMap>. The full EventEmitter surface (on, once, off, addListener, removeListener, removeAllListeners, listenerCount, etc.) is available.

Event	Trigger	Notes
`show`	Native backend accepted the notification	May fire before the notification is visually displayed
`click`	User activated the notification or an action button	`event.action` contains the action ID, or `""` for default activation
`close`	Backend reported dismissal, expiry, or native closure
`error`	Display or response handling failed	`event.error` is an `Error` instance

`NotificationEvent`

type

NotificationEventName

The event name: "click", "close", "error", or "show".

target

Notification

The Notification instance that emitted the event.

action

string | undefined

For click events: the action identifier of the button clicked, or "" for a default (body) click. undefined for other event types.

error

Error | undefined

For error events: the underlying error. undefined for other event types.

On Windows, WebviewJS checks the global toast notification setting before submission. If notifications are disabled in Windows Settings, the instance emits error instead of show. Other OS-level policies such as Do Not Disturb can still suppress presentation after the native backend accepts a notification.

Platform Notes

macOS

Uses the macOS User Notifications framework. requireInteraction keeps the notification banner on screen. Temporary PNG files are written for image buffers and cleaned up automatically.

Windows

Uses the Windows Toast notification system. WebviewJS checks the global toast setting before submission and emits error if notifications are disabled in Windows Settings. Temporary PNG files are written for image buffers.

Linux

Uses the XDG/D-Bus notification protocol. Decoded image pixels are sent directly to the notification server. close() is functional on this platform. Exact appearance depends on the desktop environment and notification daemon.

Android / iOS

The JavaScript API is fully exposed for source compatibility, but no notification is displayed and no lifecycle events are emitted.

Examples

import { Notification } from '@webviewjs/webview';

const notification = new Notification('Build complete', {
  body: 'The release executable is ready.',
  icon: './assets/app.png',
  requireInteraction: true,
});

notification.on('show',  ()          => console.log('notification shown'));
notification.on('click', ()          => console.log('notification clicked'));
notification.on('close', ()          => console.log('notification closed'));
notification.on('error', ({ error }) => console.error('notification error:', error));

Core

UI & Notifications

Reference

Native Desktop Notification API for WebviewJS Apps

Permissions

Constructor

Static Members

`Notification.permission`

`Notification.requestPermission()`

Instance Properties (readonly)

Event Handler Properties

Methods

`close()`

`on(event, listener)`

Events

`NotificationEvent`

Platform Notes

Examples

Build docs developers (and LLMs) love

Core

UI & Notifications

Reference

Documentation Index

​Permissions

​Constructor

​Static Members

​Notification.permission

​Notification.requestPermission()

​Instance Properties (readonly)

​Event Handler Properties

​Methods

​close()

​on(event, listener)

​Events

​NotificationEvent

​Platform Notes

​Examples

Build docs developers (and LLMs) love

Permissions

Constructor

Static Members

`Notification.permission`

`Notification.requestPermission()`

Instance Properties (readonly)

Event Handler Properties

Methods

`close()`

`on(event, listener)`

Events

`NotificationEvent`

Platform Notes

Examples