getNotifications

Introduction

getNotifications is a synchronous function that returns all current toast notifications visible in the Windows Action Center as an array of ToastNotificationSnapshot objects. Use this function to query the present notification state without setting up a listener.

Signature

function getNotifications(): ToastNotificationSnapshot[]

Usage

Call getNotifications when you need a one-time snapshot of all active toast notifications. This is useful for displaying notification counts, building a notification inbox UI, or inspecting which apps have pending notifications.

Tips

If you need real-time updates as notifications arrive or disappear, use startListening with a callback instead of polling getNotifications.

Note

This function requires prior access permission. Call requestAccess before using getNotifications. If access has not been granted, the function may return an empty array.

Warning

When notification suppression is enabled via enableSuppression, this function always returns an empty array. Call isSuppressionEnabled to check the current state if you get unexpected results.

Return Value

Returns an array of ToastNotificationSnapshot objects. Each snapshot captures the notification's ID, originating app, display content, and creation timestamp.

If no notifications are present (or suppression is enabled), returns an empty array [].

Example

TypeScript

import { getNotifications, requestAccess } from '@eisland/windows-toast-listener';

// Ensure we have permission to read notifications
const status = requestAccess();
if (status !== 'allowed') {
  console.log('Notification access denied');
} else {
  // Query all current toast notifications
  const notifications = getNotifications();
  console.log(`${notifications.length} notification(s) found`);

  // Iterate and display each notification
  notifications.forEach((n) => {
    console.log(`  [${n.appDisplayName}] ${n.title}: ${n.body}`);
  });
}

JavaScript

const { getNotifications, requestAccess } = require('@eisland/windows-toast-listener');

// Ensure we have permission to read notifications
const status = requestAccess();
if (status !== 'allowed') {
  console.log('Notification access denied');
} else {
  // Query all current toast notifications
  const notifications = getNotifications();
  console.log(`${notifications.length} notification(s) found`);

  // Iterate and display each notification
  notifications.forEach((n) => {
    console.log(`  [${n.appDisplayName}] ${n.title}: ${n.body}`);
  });
}

Notes

Note

The texts field in each snapshot is a flattened array of all text content (title and body included), which is useful when you need to search across all text without caring about the structure.

Note

The createdAt field is a Unix timestamp in milliseconds. Use new Date(n.createdAt) to convert it to a JavaScript Date object.

Tips

The returned array is a copy of the current state. Modifications to the returned array do not affect the internal notification store.

Danger Avoidance

Caution

Do not call getNotifications in a tight polling loop (e.g. setInterval with small intervals). Each call queries the Windows notification subsystem synchronously. Excessive polling can degrade system performance. Use startListening for event-driven monitoring instead.

Caution

Do not assume getNotifications returns persistent data. Notifications can be dismissed by the user or the system at any time. The snapshot returned reflects the moment of the call; subsequent calls may return different results.