How to Set Application Badges with JavaScript

The Badging API is a web platform standard that allows installed web applications to display an operating system-level notification badge directly on their app icon. This article explains what the Badging API is, where it is supported, and how to use modern JavaScript methods like navigator.setAppBadge() and navigator.clearAppBadge() to set numeric counts, display generic indicators, and clear badges from both the main UI thread and background service workers.

What is the Badging API?

The Badging API provides a subtle, non-intrusive way for web applications to notify users of new status updates, unread messages, notifications, or background activity. Instead of interrupting the user with system banners or dialogs, the API displays a small visual marker (a badge) directly on the application’s icon in the device’s taskbar, dock, or home screen.

Key details of the API include: - PWA Requirement: It is primarily designed for installed Progressive Web Apps (PWAs) running in standalone windows. - Cross-Platform: It works across supported operating systems including Windows, macOS, Android, and ChromeOS. - Asynchronous Execution: All badging methods return JavaScript Promises, making them non-blocking.

Checking for Browser Support

Before attempting to set or clear badges, verify that the user’s browser and runtime environment support the Badging API:

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

Setting an Application Badge

To display or update a badge, call navigator.setAppBadge(). This method can set a specific number or display an indeterminate dot depending on whether a parameter is provided.

Setting a Numeric Value

Pass an integer greater than zero to display an exact count of unread items:

async function updateUnreadCount(count) {
  try {
    if ('setAppBadge' in navigator) {
      await navigator.setAppBadge(count);
    }
  } catch (error) {
    console.error('Failed to set app badge:', error);
  }
}

// Example: Display a badge with the number 5
updateUnreadCount(5);

If the count exceeds the display limit set by the operating system (e.g., 99+), the OS automatically formats the number to fit the icon design.

Setting an Indeterminate (Generic) Badge

If you call setAppBadge() without any arguments, the platform displays an indeterminate badge (typically a colored dot) indicating that an update is available without specifying a count:

async function showGenericNotification() {
  try {
    if ('setAppBadge' in navigator) {
      await navigator.setAppBadge();
    }
  } catch (error) {
    console.error('Failed to set generic badge:', error);
  }
}

showGenericNotification();

Clearing an Application Badge

To remove a badge from the application icon, use navigator.clearAppBadge(). Alternatively, passing 0 to navigator.setAppBadge(0) also clears the badge:

async function removeAppBadge() {
  try {
    if ('clearAppBadge' in navigator) {
      await navigator.clearAppBadge();
    }
  } catch (error) {
    console.error('Failed to clear app badge:', error);
  }
}

// Clear the badge when the user has read all notifications
removeAppBadge();

Using the Badging API in Service Workers

The Badging API is available within the ServiceWorkerGlobalScope, allowing applications to update badges in the background, such as when receiving push notifications:

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

  event.waitUntil(
    (async () => {
      if ('setAppBadge' in self.navigator) {
        await self.navigator.setAppBadge(unreadCount);
      }
    })()
  );
});

Using the API within service workers ensures that the app icon remains accurate even when the application window is closed.