electron-windows-notifications

The appUserModelId identifies your application in Windows.

• In Electron: You can set this at runtime using app.setAppUserModelId().
• In this module: If you do not pass appId to the notification constructor, the module assumes it is a global property on Electron's main thread.
• Recommendation: Unless running inside a UWP container, you should explicitly pass the appId to the constructor.

The module uses util.format to perform printf-like string replacement within your XML templates. Placeholders in the template string are replaced by values provided in the strings array.

Supported Placeholders:

• %s: String
• %d: Number (integer or float)
• %j: JSON
• %%: A single percent sign (%)

Important: If a placeholder does not have a corresponding argument in the strings array, it will not be replaced. To avoid XML syntax errors, always use the strings property for dynamic content to ensure proper XML escaping.

Install the package via npm to use native Windows toast and tile notifications (Windows 8, 8.1, and 10) via WinRT bindings.

Note for Electron v14+: You must require NodeRT modules in the main process.

npm install --save electron-windows-notifications

To set up and run the Electron sample application, navigate to the sample directory, install dependencies, and rebuild the native modules for the Electron version used in the app. Finally, start the application using npm.

Note: The rebuild command assumes a Windows environment using the local electron-rebuild binary.

cd samples\electron
npm install
.\node_modules\.bin\electron-rebuild -m .\app\node_modules
npm start

The electron-windows-notifications library provides an interface for sending Windows Toast notifications and Tile notifications.

Platform Compatibility: This library is designed specifically for Windows. If run on a non-Windows platform or an unsupported Windows version (versions other than 8, 8.1, or 10.0), the library exports 'no-op' (no-operation) versions of its classes and methods. These no-ops prevent the application from crashing but will not trigger any actual notifications.

Supported Windows Versions:

• Windows 10 (10.0)
• Windows 8.1 (8.1)
• Windows 8 (8)

const notifications = require('electron-windows-notifications');

// On supported Windows versions, you can access:
// notifications.getToastNotifier()
// notifications.TileNotification
// notifications.history
// etc.

Use the TileNotification class to update the app's primary or secondary tiles. This requires the app to be running inside the UWP model (Windows 10 Anniversary Update and later).

Note: For UWP support in Electron, see electron-windows-store.

The constructor accepts an options object with the following properties:

• template (string): The XML template for the notification.
• strings (string[]): An array of strings used to replace placeholders in the template.
• tag (string): Unique identifier of this notification within the notification group.
• tileId (string): If set, the specific tile will be updated. Otherwise, the app's primary tile is used.

// Note: The README provides a ToastNotification example for TileNotification usage.
// Ensure you are running in a UWP container for tile updates to work.

The SecondaryTile class provides static methods to retrieve existing tiles currently pinned to the Start screen.

• SecondaryTile.findAll(): Returns a Promise that resolves with an array of all secondary tiles found on the system.
• SecondaryTile.findAllForPackage(): Returns a Promise that resolves with an array of all secondary tiles belonging specifically to your application's package.

const SecondaryTile = require('electron-windows-notifications').SecondaryTile;

// Find all tiles for your specific app package
SecondaryTile.findAllForPackage()
  .then(tiles => {
    console.log('Existing tiles for this app:', tiles);
  })
  .catch(err => {
    console.error('Error finding tiles:', err);
  });

You can enable the notification queue, which allows the tile to queue up to five notifications. This can be enabled globally for all tile sizes or specifically for certain dimensions.

Available methods:

• enableNotificationQueue(value): Enables queuing for all tile sizes. Defaults to true.
• enableNotificationQueueForSquare150x150(value): Enables queuing specifically for the medium tile. Defaults to true.
• enableNotificationQueueForSquare310x310(value): Enables queuing specifically for the large tile. Defaults to true.
• enableNotificationQueueForWide310x150(value): Enables queuing specifically for the wide tile. Defaults to true.

const updater = new TileUpdater();

// Enable queuing for all sizes
updater.enableNotificationQueue(true);

// Or specifically for a size
updater.enableNotificationQueueForSquare310x310(true);

Once a ToastNotification instance is created, use the following methods to control its visibility:

• show(): Displays the notification. This method performs a check against Windows notification settings (via checkSettings()) before attempting to show the toast. If notifications are disabled by the manifest, group policy, user settings, or application settings, the failed event will be emitted.
• hide(): Hides the currently active toast notification.

const notification = new ToastNotification({
  template: '<toast><visual><binding template="ToastGeneric">%s</binding></visual></toast>',
  strings: ['Message text']
});

// Display the notification
notification.show();

// Hide the notification
notification.hide();