Skip to content

API in Installation

Badging API

Published Updated

Limited availabilityNot supported in Chrome (Android), Firefox (Desktop), Firefox (Android)W3C draft

The Badging API (navigator.setAppBadge() and navigator.clearAppBadge(), also exposed on WorkerNavigator inside a service worker) places a number or a plain dot on an installed web app’s icon in the taskbar, Dock, or Home Screen. Chrome 81 and Edge 81 draw it on Windows and macOS, and Chrome 91 on ChromeOS; Safari 16.4 draws it for Home Screen web apps on iOS and Safari 17 for Dock web apps on macOS Sonoma and later; browser-compat-data records no support in Chrome for Android, Samsung Internet or Android WebView, and Firefox has no implementation (BCD api.Navigator.setAppBadge).

await navigator.setAppBadge(); // a dot (a "flag"), no number
await navigator.setAppBadge(contents); // a number; 0 clears
await navigator.clearAppBadge(); // removes the badge
// Inside a service worker, for example from a push handler
self.navigator.setAppBadge(count);

Both methods return a Promise<void> that fulfils when the request has been handed to the operating system, not when the badge is visible. No permission prompt is involved on Chromium; on iOS the badge is only drawn once the user has allowed notifications for the installed app.

Only setAppBadge() takes an argument.

Name Type Description
contents unsigned long long, optional The number to show. 0 clears the badge, the same as clearAppBadge(). When omitted, the badge is set to the “flag” state, which the specification asks the platform to show as a non-numeric indicator such as a coloured dot, or, where flags are unsupported, as the closest equivalent such as “1”. The operating system decides how large numbers render; the specification calls the value a hint and allows the platform to abbreviate it.

setAppBadge() rejects in four cases, and in two others it resolves without an error while no badge is visible.

  • TypeError: contents cannot be converted under [EnforceRange] unsigned long long: NaN, an infinity, or a value that is still negative or above 2^53 − 1 after truncation toward zero (Web IDL truncates first, so 3.5 sets 3 and -0.5 sets 0). The method returns a promise, and Web IDL turns an argument-conversion error in a promise-returning operation into a rejected promise rather than a synchronous throw.
  • InvalidStateError: the calling document is not fully active (for example, a detached iframe), per the specification’s first step for both methods.
  • SecurityError: the calling document’s origin is not same origin-domain with the top-level origin, for example a cross-origin iframe.
  • NotAllowedError: the browser requires notification permission to set a badge and the permission is not granted. The specification allows this; WebKit does not do it (next case).
  • No error, no badge: the app is not installed. Chrome’s badging guide says the API requires an installed app and advises calling it whenever it exists regardless of install state; a call from a site that is not installed draws nothing.
  • No error, no badge: on iOS 16.4 and later the Home Screen web app has not been granted notification permission. WebKit’s 16.4 post says both methods change the count “even before permission to display the count has been granted”, and the icon shows the current count as soon as the user allows notifications.

In Firefox navigator.setAppBadge is undefined, so an unguarded call throws TypeError before the API is reached.

Badge updates can run in a service worker or in the page. Provide a fallback for browsers without the API.

Mirroring an unread count from a push event

Section titled “Mirroring an unread count from a push event”

A push payload that carries the server’s unread count can update the icon before the user opens the app. event.waitUntil() keeps the worker alive until the badge call settles; calling clearAppBadge() from the page once the user has seen the inbox removes a badge that is no longer needed.

sw.js
self.addEventListener('push', (event) => {
const data = event.data?.json() ?? {};
const unread = Number.isInteger(data.unread) ? data.unread : 0;
event.waitUntil(Promise.all([
self.registration.showNotification(data.title ?? 'New message'),
self.navigator.setAppBadge(unread),
]));
});
// page.js, when the inbox view is shown
navigator.clearAppBadge?.();

Chrome’s badging guide says most browsers, Chrome included, require a notification when a push message arrives, so a push handler cannot update the badge silently; WebKit goes further and revokes a subscription whose push event shows no notification (WebKit, “Meet Web Push”). The notification call above is therefore not optional. For a silent badge update, Chrome’s guide points to updating it while the page is open or from Periodic Background Sync.

Detecting support and falling back to the document title

Section titled “Detecting support and falling back to the document title”

Where setAppBadge is missing, use the tab title, which is available in all browsers; MDN notes that sites have long put status in the title or the favicon. The fallback below prefixes it with the count and removes the prefix when the count is zero.

function showUnread(count) {
if ('setAppBadge' in navigator) {
return count > 0 ? navigator.setAppBadge(count) : navigator.clearAppBadge();
}
// No Badging API (for example Firefox): use the title. Chromium exposes the API on sites that are not installed too, where it draws nothing.
const base = document.title.replace(/^\(\d+\) /, '');
document.title = count > 0 ? `(${count}) ${base}` : base;
return Promise.resolve();
}

The title fallback gives Firefox users a visible count while the tab is open. The Badging API removes that limitation.

Specifications

SpecificationStatus
Badging APIW3C draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes81highsource123
Chrome (Android)#No—highsource4
Edge (Desktop)#Yes81highsource5678
Firefox (Desktop)#No—highsource9
Firefox (Android)#No—highsource1011
Safari (macOS)#Yes17highsource1213
Safari (iOS)#Yes16.4highsource1415
Samsung Internet#No—highsource1617
WebView (Android)#No—highsource1819
  1. Windows and macOS since Chrome 81.
  2. ChromeOS since Chrome 91.
  3. Linux offers no universal badging API on the operating system level.
  4. No Chrome Android support is recorded in browser-compat-data.
  5. Windows and macOS since Chrome 81.
  6. ChromeOS since Chrome 91.
  7. Linux offers no universal badging API on the operating system level.
  8. Derived by browser-compat-data mirroring from Chrome.
  9. No Firefox support is recorded in browser-compat-data.
  10. No Firefox for Android support is recorded in browser-compat-data.
  11. Derived by browser-compat-data mirroring from Firefox.
  12. Badging is supported for installed web apps on macOS Sonoma and higher.
  13. Passing `0` as an argument will clear the badge instead of displaying an unnumbered dot.
  14. Badging is supported for web apps saved to the home screen.
  15. Passing `0` as an argument will clear the badge instead of displaying an unnumbered dot.
  16. No Samsung Internet support is recorded in browser-compat-data.
  17. Derived by browser-compat-data mirroring from Chrome Android.
  18. No WebView Android support is recorded in browser-compat-data.
  19. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/badging-api.json · Global usage: 57 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-20 · Confidence: high (computed from sources)