Display a badge on the app icon

App badges are only supported when a PWA is installed on its host operating system. Badges appear on the app icon which only exists after the app has been installed.

On desktop operating systems, badges are only supported on Windows and macOS, and only when the PWA is installed from Chrome or Edge. While the Badging API is supported on Chromium-based browsers on Linux, badges are not displayed on this operating system.

Safari and Firefox on desktop do not support the Badging API and do not support installing PWAs.

Badges are supported in Safari on iOS and iPadOS, starting with iPadOS 16.4. The badging API is not supported on Chromium-based browsers running on Android. Instead, Android automatically shows a badge on the PWA's app icon when there is an unread notification, just as it does for Android apps.

Before learning how to use badges, consider these best practices to ensure your app uses badges in the most effective and useful way for your users.

To ensure the Badging API is supported in the user's browser and operating system, to prevent throwing a JavaScript error, check for support before using the API:

if (navigator.setAppBadge) {
  // The API is supported, use it.
} else {
  // The API is not supported, don't use it.
}

Do not rely solely on badges to inform users about the availability of new content. Browsers that support the Badging API may be installed on operating systems that do not support displaying a badge. For example, while Chrome supports the Badging API, badges will not appear on installed application icons on Linux.

While notification badges are supported on iOS and iPadOS, badges will not appear until the application is granted notification permissions. To request notification permissions, call the Notification.requestPermission() method:

Notification.requestPermission().then((result) => {
  console.log(result);
});

Optionally, you can check if a user has previously granted notification permissions using the Permissions API.

Like notifications, badges can be a very effective way to re-engage users with your app when used sparingly. Make sure to use badges to only signal new content that's important for your users to know about.

Make sure to update your application badge in real-time. This means updating the badge count to reflect how many new items are actually left for the user to consume, and clearing the app badge when there are no new items.

For example, if an email client app receives new messages in the background, it should update its badge to display the right number of unread messages in the inbox, potentially filtering out messages from other folders such as a spam folder. It's possible to update badges in the background by using the navigator.setAppBadge() method from a service worker.

Once the user launches the app and starts reading messages, the email client app should update its badge accordingly by calling navigator.setAppBadge() with the new unread messages count, or by calling navigator.clearAppBadge() when there are no unread messages.

When your app receives new content and adds a badge on the app icon, make sure to highlight that new content for users when they launch the app.

For example, if an email client app displays the unread messages count on the app icon badge, then those messages should be bolded or highlighted in some way when the app is opened.

To display a badge on your PWA's app icon that shows a number of unread messages, use the Navigator.setAppBadge() method:

// Check for support first.
if (navigator.setAppBadge) {
  // Display the number of unread messages.
  navigator.setAppBadge(numberOfUnreadMessages);
}

You can also display an empty badge using the same method by omitting the count parameter, or setting it to 0:

// Check for support first.
if (navigator.setAppBadge) {
  // Just display the badge, with no number in it.
  navigator.setAppBadge();
}

To remove the badge on the app icon, use the Navigator.clearAppBadge() method:

// Check for support first.
if (navigator.clearAppBadge) {
  // Remove the badge on the app icon.
  navigator.clearAppBadge();
}

Badges can be useful to re-engage users with your app when they're not already using the app. This means that your app must be able to update its badge even when it's not running.

PWAs can use the following mechanisms to update in the background and display, update, or hide their badges:

Push API

PWAs can use this API to receive messages from a server even when the app is not running. Most browsers require a notification to be displayed whenever a push message is received. This is fine for some use cases (for example, showing a notification when updating the badge), but makes it impossible to subtly update the badge without displaying a notification. In addition, users must grant your site notification permission in order to receive push messages. For more information, see the ServiceWorkerRegistration: showNotification() method.

Background Synchronization API

PWAs can use this API to run code in the background when a stable network connection is detected.

Web Periodic Background Synchronization API

PWAs can use this API to run code in the background at periodic intervals of time.

Here is a service worker code example showing how to listen to a server's Push messages and update the app badge to reflect an unread messages count:

// Listen to "push" events in the service worker.
self.addEventListener("push", (event) => {
  // Extract the unread count from the push message data.
  const message = event.data.json();
  const unreadCount = message.unreadCount;

  // Set or clear the badge.
  if (navigator.setAppBadge) {
    if (unreadCount && unreadCount > 0) {
      navigator.setAppBadge(unreadCount);
    } else {
      navigator.clearAppBadge();
    }
  }
  // It's obligatory to show the notification to the user.
  self.registration.showNotification(`${unreadCount} unread messages`);
});

• How to create an app badge
• Badging for app icons
• Re-engage users with badges, notifications, and push messages
• Codelab: Build a push notification server