JavaScript Badging API: Set and Clear Icon Badges

The Badging API provides a native-like mechanism for web applications and Progressive Web Apps (PWAs) to display subtle notification indicators directly on the application’s icon in the operating system’s taskbar, dock, or home screen. This article explains how to detect Badging API support, set numeric and non-numeric badges using navigator.setAppBadge(), clear them using navigator.clearAppBadge(), and handle badge updates from both foreground scripts and background service workers.

Feature Detection

Before invoking badge methods, verify that the user’s browser and operating system support the Badging API:

if ('setAppBadge' in navigator && 'clearAppBadge' in navigator) {
  console.log('Badging API is supported.');
} else {
  console.log('Badging API is not supported.');
}

The Badging API generally functions when the web application is installed as a PWA and runs on supported platforms such as Windows, macOS, ChromeOS, and Android.

Setting an Application Badge

To set a badge on the application icon, use the asynchronous navigator.setAppBadge() method. This method returns a Promise that resolves once the badge is displayed.

1. Setting a Numeric Badge

Pass an integer greater than zero to display a specific count (e.g., unread messages or pending tasks):

async function updateUnreadCount(count) {
  try {
    await navigator.setAppBadge(count);
    console.log(`Badge set to ${count}`);
  } catch (error) {
    console.error('Failed to set badge:', error);
  }
}

// Example usage
updateUnreadCount(5);

If the number passed exceeds the operating system’s display limit (often 99 or 99+), the platform automatically caps or formats the display (e.g., showing 99+ or a dot).

2. Setting a Non-Numeric Indicator

Calling setAppBadge() without arguments displays a generic flag, dot, or generic marker indicating new activity without showing a specific number:

async function setGenericBadge() {
  try {
    await navigator.setAppBadge();
    console.log('Generic badge set.');
  } catch (error) {
    console.error('Failed to set generic badge:', error);
  }
}

Clearing an Application Badge

To remove the badge from the application icon, call navigator.clearAppBadge(). This method also returns a Promise.

async function removeBadge() {
  try {
    await navigator.clearAppBadge();
    console.log('Badge cleared.');
  } catch (error) {
    console.error('Failed to clear badge:', error);
  }
}

Alternatively, passing 0 to navigator.setAppBadge(0) functions identically to clearAppBadge().

Updating Badges in the Background via Service Workers

The Badging API is accessible in the ServiceWorkerGlobalScope, allowing badges to be updated when receiving background push events, even if the application is not currently open in a browser tab.

// Inside service-worker.js
self.addEventListener('push', (event) => {
  const data = event.data ? event.data.json() : {};
  const unreadCount = data.unreadCount || 1;

  event.waitUntil(
    self.navigator.setAppBadge(unreadCount)
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  
  event.waitUntil(
    self.navigator.clearAppBadge()
  );
});

Using the Badging API provides a non-intrusive way to keep users informed of status updates without relying solely on disruptive system notifications.