JavaScript Navigator setAppBadge() Method

What You’ll Learn

navigator.setAppBadge() sets a badge on your installed app icon — for example an unread count. Learn numeric badges, flag badges, clearing with 0 / clearAppBadge(), five examples, and try-it labs.

Introduction

Chat and mail apps show a small number on the home-screen icon when messages are unread. On the web, the Badging API lets an installed PWA do the same.

Call navigator.setAppBadge(contents) to set a count, or navigator.setAppBadge() with no argument for a simple “something is new” indicator (dot / flag, depending on the OS).

Understanding the setAppBadge() Method

• Optional number — contents becomes the badge value.
• No argument — platform shows a flag/dot-style badge.
• 0 clears — sets the badge to nothing (same idea as clear).
• Promise — resolves with undefined on success.
• Secure context — HTTPS / localhost.
• Best on installed apps — dock / home-screen icons, not ordinary tabs.

📝 Syntax

General forms of the method:

navigator.setAppBadge()
navigator.setAppBadge(contents)

Parameters

• contents (optional) — a number used as the badge value. If 0, the badge is cleared.

Return value

• A Promise that fulfills with undefined.

Common exceptions / rejections

• InvalidStateError — document not fully active.
• SecurityError — blocked by same-origin policy in some cases.
• NotAllowedError — permission not granted.

MDN-style unread count

const unread = 30;
navigator.setAppBadge(unread);

Examples Gallery

Examples feature-detect first. On an ordinary browser tab you may get a resolved Promise with no visible badge — install as a PWA on a supporting OS to see the icon update.

const lines = [
  "setAppBadge: " +
    (typeof navigator.setAppBadge === "function" ? "available" : "missing"),
  "clearAppBadge: " +
    (typeof navigator.clearAppBadge === "function" ? "available" : "missing"),
  "isSecureContext: " + window.isSecureContext
];
console.log(lines.join("\n"));

setAppBadge: available
clearAppBadge: available
isSecureContext: true
(or missing on unsupported browsers)

async function setUnreadBadge(unread) {
  if (typeof navigator.setAppBadge !== "function") {
    return "Badging API not supported";
  }
  try {
    await navigator.setAppBadge(unread);
    return "Badge set to " + unread;
  } catch (err) {
    return "Error: " + err.name;
  }
}

setUnreadBadge(30).then(console.log);

Badge set to 30
(or Error: NotAllowedError / Badging API not supported)

async function setFlagBadge() {
  if (typeof navigator.setAppBadge !== "function") {
    return "API missing";
  }
  try {
    await navigator.setAppBadge();
    return "Flag / dot badge requested";
  } catch (err) {
    return "Error: " + err.name;
  }
}

setFlagBadge().then(console.log);

Flag / dot badge requested

async function clearWithZero() {
  if (typeof navigator.setAppBadge !== "function") {
    return "API missing";
  }
  await navigator.setAppBadge(3);
  await navigator.setAppBadge(0);
  return "Badge cleared via setAppBadge(0)";
}

clearWithZero().then(console.log).catch((err) => {
  console.log("Error: " + err.name);
});

Badge cleared via setAppBadge(0)

async function syncAppBadge(unread) {
  if (typeof navigator.setAppBadge !== "function") {
    return { ok: false, reason: "unsupported" };
  }
  if (!window.isSecureContext) {
    return { ok: false, reason: "insecure-context" };
  }
  try {
    if (unread > 0) {
      await navigator.setAppBadge(unread);
      return { ok: true, reason: "set", unread: unread };
    }
    if (typeof navigator.clearAppBadge === "function") {
      await navigator.clearAppBadge();
    } else {
      await navigator.setAppBadge(0);
    }
    return { ok: true, reason: "cleared", unread: 0 };
  } catch (err) {
    return { ok: false, reason: err.name };
  }
}

syncAppBadge(7).then((r) => console.log(JSON.stringify(r)));
syncAppBadge(0).then((r) => console.log(JSON.stringify(r)));

{"ok":true,"reason":"set","unread":7}
{"ok":true,"reason":"cleared","unread":0}

🚀 Common Use Cases

• Unread messages — show how many chats need attention.
• Task queues — badge pending review items for a work PWA.
• Cart / wishlist — subtle flag when something was added offline.
• Notification sync — update badge when push arrives while the app is closed.
• Clear on read — remove the badge when the user opens the inbox.

📝 Notes

• Limited availability (not Baseline) — feature-detect always.
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Requires a secure context (HTTPS / localhost).
• Visible badges are most reliable on installed PWAs.
• Related: clearAppBadge(), share(), canShare(), sendBeacon().

💡 Best Practices