Web App Badging API

How use a badge for your installed PWA

Every app deserves a badge

It’s a very common UI pattern you see everyday for the native apps on your device: a notification badge. It’s a great concept that informs users about some missed information via a simple and small indicator. Most commonly it’s a counter and for some special apps, a custom badge or visual adjustment to the icon is used, for example on macOS’ Keychain-app, where an orange coin indicates that the keychain is unlocked and accessible.

But back to the default badging. Thanks to Google steadily pushing the web forward, your installed progressive web app can display a counter as badge as well.


In order for your web app to be able to show a badge, it has to meet Google’s “installability criteria”, linked below in the addendum. And this makes absolutely sense: your PWA has to be installed on a device in order to have a fixed place in your system. On Windows, your apps live in the task bar and on macOS it’s in the Dock.

If you don’t know yet, your web app can be progressively enhanced to evolve into a new class of applications called “Progressive Web Apps”, or PWA for short. PWAs support a wide variety of new features that were previously only available to native apps. You can check out many articles about PWAs on this web app, which is a PWA itself that can be installed.

Note that support for the App Badging API is currently limited to Chromium Browsers and only supported on Desktop devices as well as Android. The overall state of the API is stable for Chromium, but not supported by any means by other browsers. Therefore usage shouldn’t be a mandatory requirement to use the app, but rather progressively enhance the existing UX.

How it works

The actual implementation is very straightforward and only requires a few lines of code to cover all use cases.

// These code examples asume you're using
// Typescript, as they use optional chaining.
// Also note that the API-calls for badging
// return a promise that can directly be
// catched.

async function setSimpleBadge(){
  // Just a simple indicator without any value.
  // This is the simplest variant of a badge.
  await navigator?.setClientBadge();

async function incrementBadgeCount(){
  // Get our dummy count and update it,
  // just to give more context for this demo.
  const countNow = getUnreadMessagesCount();
  await setUnreadMessagesCount(countNow + 1);
  // Update the UI.
  await navigator.setAppBadge(countNow + 1)
    .catch((error) => { /* ... */ });

async function resetBadge(){
  // As simple as it gets: reset the badge UI.
  await navigator.clearClientBadge();

A very nice aspect of this new API is that it can be used inside your Service Worker as well, which means that, if implemented, your installed PWA can fetch data in the background and receive push notifications, which in turn can update your app’s badge!


As you’ve seen, using the App Badging API is really simple. All that’s required for you to test is a Chromium-based browser as well as a simple PWA that can be installed. It’s not to be expected that this API will be available on Safari or Firefox any time soon, as this also implies more commitment to PWAs in general by those teams. But for an enhanced UX for your web app where possible, it’s a great win and should definitely be used!