> ## Documentation Index
> Fetch the complete documentation index at: https://webview.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop Notifications

> Learn how to display native desktop notifications, handle user interactions, and create actionable notifications in your Node.js desktop application.

Desktop notifications are a simple way to inform users about events while your application is running in the background.

WebviewJS provides a browser-compatible `Notification` API, so if you've previously used the Web Notifications API, the same patterns work here without requiring a browser or service worker.

## Creating your first notification

The simplest notification only needs a title.

```js theme={null}
import { Notification } from '@webviewjs/webview';

new Notification('Hello!');
```

Most applications also include a message body.

```js theme={null}
import { Notification } from '@webviewjs/webview';

new Notification('Build complete', {
  body: 'Your application compiled successfully.',
});
```

Unlike browser notifications, there is no `show()` method. The notification is displayed immediately when constructed.

***

## Displaying an icon

You can provide either a platform icon name or a path to an image.

```js theme={null}
new Notification('Download finished', {
  body: 'Your archive is ready.',
  icon: './assets/icon.png',
});
```

On Linux, you may also use freedesktop icon names.

```js theme={null}
new Notification('Mail', {
  icon: 'mail-unread',
});
```

***

## Displaying an image

Notifications can include a larger preview image.

```js theme={null}
import { readFile } from 'node:fs/promises';
import { Notification } from '@webviewjs/webview';

const screenshot = await readFile('./preview.png');

new Notification('Screenshot captured', {
  body: 'Click to view',
  image: screenshot,
});
```

Passing a `Buffer` is useful when the image was downloaded or generated entirely in memory.

***

## Responding to notification events

Notifications are `EventEmitter`s.

```js theme={null}
const notification = new Notification('Build complete', {
  body: 'Click to open the output folder.',
});

notification.on('show', () => {
  console.log('Shown');
});

notification.on('click', () => {
  console.log('Clicked');
});

notification.on('close', () => {
  console.log('Dismissed');
});

notification.on('error', ({ error }) => {
  console.error(error);
});
```

You can also use browser-style event handlers.

```js theme={null}
notification.onclick = () => {
  console.log('Clicked');
};

notification.onclose = () => {
  console.log('Closed');
};
```

***

## Action buttons

Long-running applications often provide quick actions directly inside notifications.

```js theme={null}
const notification = new Notification('Download complete', {
  body: 'Choose what to do next.',

  persistent: true,

  actions: [
    {
      action: 'open',
      title: 'Open',
    },
    {
      action: 'dismiss',
      title: 'Dismiss',
    },
  ],
});

notification.on('click', ({ action }) => {
  switch (action) {
    case 'open':
      openDownload();
      break;

    case 'dismiss':
      notification.close();
      break;

    default:
      console.log('Notification body clicked');
  }
});
```

Action buttons require `persistent: true`. Attempting to use actions without persistence throws a `TypeError`.

***

## Persistent notifications

By default, notifications are fire-and-forget.

If the rest of your application exits immediately afterwards, the notification will no longer receive interaction events.

Enable persistence when the user needs to interact with the notification.

```js theme={null}
new Notification('Backup finished', {
  persistent: true,
});
```

Persistent notifications keep the Node.js process alive until the notification is dismissed or interacted with.

***

## Closing a notification

On supported platforms you can close a notification yourself.

```js theme={null}
notification.close();
```

On platforms that do not expose programmatic closing, the notification remains visible until the user dismisses it or it naturally expires.

***

## Permissions

Unlike browsers, desktop applications do not ask for notification permission.

```js theme={null}
console.log(Notification.permission);
// "granted"
```

Likewise,

```js theme={null}
await Notification.requestPermission();
```

always resolves to `"granted"` for browser compatibility.

***

## Platform differences

Some notification features vary by platform.

| Feature            | Windows | macOS   | Linux |
| ------------------ | ------- | ------- | ----- |
| Icons              | ✓       | ✓       | ✓     |
| Images             | ✓       | ✓       | ✓     |
| Action buttons     | ✓       | ✓       | ✓     |
| Lifecycle events   | ✓       | ✓       | ✓     |
| Programmatic close | Partial | Partial | ✓     |

***

## Next steps

This guide covers the most common notification workflows.

For the complete constructor, every available option, supported events, and platform-specific behavior, see the **Notification API Reference**.