JavaScript Navigator clearAppBadge() Method

What You’ll Learn

navigator.clearAppBadge() is part of the Badging API. Learn how to remove an app icon badge after unread items are handled, pair it with setAppBadge(), use secure contexts, and try five beginner examples.

Introduction

Installed Progressive Web Apps can show a small badge on their icon — a number like 3 for unread messages, or a simple flag/dot. That badge is set with navigator.setAppBadge().

When nothing is left to highlight (inbox empty, tasks done), call navigator.clearAppBadge() to remove it. The badge value becomes nothing, and the icon returns to a clean state.

Understanding the clearAppBadge() Method

clearAppBadge() is the dedicated “remove badge” call in the Badging API.

• No parameters — just call navigator.clearAppBadge().
• Sets badge to nothing — no number / flag on the icon.
• Returns a Promise — resolves with undefined on success.
• Secure context — HTTPS / localhost required.
• May reject — e.g. document not fully active, same-origin issues, or permission not granted (NotAllowedError).
• Alternative — setAppBadge(0) also clears the badge.

📝 Syntax

General form of the method:

navigator.clearAppBadge()

Parameters

• None.

Return value

• A Promise that resolves with undefined.

Common patterns

// MDN: clear after messages are read
navigator.clearAppBadge();

// Safer async pattern with feature detect
async function clearBadgeSafe() {
  if (!navigator.clearAppBadge) {
    return "Badging API not supported";
  }
  try {
    await navigator.clearAppBadge();
    return "Badge cleared";
  } catch (err) {
    return "clearAppBadge error: " + err.name;
  }
}

// Pair with setAppBadge for unread counts
async function syncUnreadBadge(unread) {
  if (!navigator.setAppBadge || !navigator.clearAppBadge) return;
  if (unread > 0) {
    await navigator.setAppBadge(unread);
  } else {
    await navigator.clearAppBadge();
  }
}

Examples Gallery

Examples follow MDN Badging API patterns. Prefer Try It Yourself — a visible badge usually needs an installed PWA / home-screen app on a supporting OS.

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

clearAppBadge: missing
setAppBadge: missing
isSecureContext: true
(or "available" in supporting browsers)

if (!navigator.clearAppBadge) {
  console.log("clearAppBadge not supported");
} else {
  navigator.clearAppBadge().then(
    () => console.log("Badge cleared (or no-op on this platform)"),
    (err) => console.log("Error: " + err.name)
  );
}

clearAppBadge not supported
(or "Badge cleared…" / Error: NotAllowedError, etc.)

async function syncUnreadBadge(unread) {
  if (!navigator.setAppBadge || !navigator.clearAppBadge) {
    return "Badging API not supported";
  }
  try {
    if (unread > 0) {
      await navigator.setAppBadge(unread);
      return "Badge set to " + unread;
    }
    await navigator.clearAppBadge();
    return "Badge cleared (unread = 0)";
  } catch (err) {
    return "Badge sync error: " + err.name;
  }
}

syncUnreadBadge(0).then(console.log);

Badging API not supported
(or "Badge cleared (unread = 0)" when supported)

async function compareClearStyles() {
  if (!navigator.clearAppBadge || !navigator.setAppBadge) {
    return "Badging API not supported";
  }
  // Dedicated clear
  await navigator.clearAppBadge();
  // Equivalent clear via set
  await navigator.setAppBadge(0);
  return "Both clearAppBadge() and setAppBadge(0) clear the badge";
}

compareClearStyles().then(console.log);

Badging API not supported
(or the equivalence message when both methods work)

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

clearBadgeSafe().then((result) => {
  console.log(JSON.stringify(result));
});

{"ok":false,"reason":"unsupported"}
(or {"ok":true,"reason":"cleared"} / NotAllowedError, etc.)

🚀 Common Use Cases

• Messaging apps — clear the badge when the inbox is empty.
• Todo / reminders — remove the icon badge after tasks are completed.
• Turn-based games — clear when it is no longer the player’s turn.
• Notification hygiene — keep the dock / home screen honest after users catch up.
• Progressive PWAs — enhance installed apps without requiring badges for core UX.

📝 Notes

• Limited availability (not Baseline) — feature-detect always.
• Not Deprecated, Experimental, or Non-standard — no status banner required (MDN/BCD).
• Secure context required (HTTPS / localhost).
• Returns a Promise; pair with navigator.setAppBadge() for counts.
• Related: deprecatedReplaceInURN(), canShare(), serviceWorker, Window.

💡 Best Practices