JavaScript Navigator setAppBadge() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word SETAPPBADGE

Definition

navigator.setAppBadge(contents?) sets a badge on the icon associated with this app (Badging API). Pass a number for a count, omit it for a platform flag (dot), or pass 0 to clear.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call navigator.setAppBadge. Start with this line.

JavaScript
navigator.setAppBadge(contents?)
CallWhat it does
navigator.setAppBadge(contents?)Primary signature.
navigator.setAppBadge(...)Call with the arguments your case needs.

Built into the browser. Call setAppBadge(...) on a Navigator — no import required.

Library declarations
JavaScript
navigator.setAppBadge(contents?)

Parameters

ParameterDescription
contentsOptional. Number for the badge; omit → flag; 0 → clear
Secure contextRequired. HTTPS / localhost

Return Value

Return ValueDescription
*Promise → undefined

JavaScript Examples

Example 1 — Set an Unread Count

Pass a number so the icon can show how many items are pending (MDN).

JavaScript
if (typeof navigator.setAppBadge !== "function") {
  console.log("Badging unavailable");
} else {
  const unread = 30;
  navigator.setAppBadge(unread)
    .then(() => console.log("badge set"))
    .catch((err) => console.log(err.name));
}
Try It Yourself

How It Works

  1. Detect. Skip if the method is missing (Limited availability).
  2. Pass a count. MDN: a number becomes the badge value.
  3. Await the Promise. Resolves with undefined on success.
  4. Catch errors. Permission or state failures reject with a DOMException name.

Example 2 — Flag Badge (No Number)

Call with no argument for a platform-defined marker (dot / flag).

JavaScript
navigator.setAppBadge()
  .then(() => console.log("flag badge"))
  .catch((err) => console.log(err.name));
Try It Yourself

How It Works

  1. No contents. Badge state becomes flag (MDN).
  2. OS picks the look. Often a colored dot, not a digit.
  3. Use when you only need “attention” without a count.
  4. Still a Promise. Handle resolve / reject the same way.

Example 3 — Clear with setAppBadge(0)

Passing 0 sets the badge to nothing (same effect as clearAppBadge()).

JavaScript
navigator.setAppBadge(0)
  .then(() => console.log("cleared"))
  .catch((err) => console.log(err.name));

// Prefer when intent is only “remove”:
// await navigator.clearAppBadge();
Try It Yourself

How It Works

  1. 0 is special. MDN: never shown as a number — clears instead.
  2. State → nothing. Icon badge is removed.
  3. Dedicated clear. Prefer clearAppBadge() for intent clarity.
  4. Sync with UI. Clear when your in-app unread count hits zero.
Compatibility

Browser Support

Navigator.setAppBadge() is part of the Badging API. MDN marks it Limited availability (not Baseline). Requires a secure context.

✓ Limited availability

Navigator.setAppBadge()

Best support in Chromium-based browsers for installed PWAs. Missing or partial on Firefox and some platforms — always feature-detect.

Limited Not Baseline
Google Chrome PWA / modern (secure)
Yes
Microsoft Edge PWA / modern (secure)
Yes
Opera PWA / modern (secure)
Yes
Apple Safari Partial / platform-dependent
Partial
Mozilla Firefox Not supported
No
Internet Explorer Not supported
No
setAppBadge() Feature-detect required

Bottom line: Ship badging only after detecting the method and handling Promise errors. See the MDN setAppBadge() reference.

Frequently Asked Questions

It sets a badge on the icon associated with the app. Pass a number to show that count, omit the argument for a platform flag/dot, or pass 0 to clear the badge (set it to nothing).
No. MDN does not mark it Deprecated, Experimental, or Non-standard. It is Limited availability (not Baseline) and requires a secure context.
Yes. The Badging API is a secure-context feature (HTTPS or localhost) in supporting browsers.
A Promise that resolves with undefined when the badge is set. Handle rejections for InvalidStateError, SecurityError, or NotAllowedError.
Call navigator.clearAppBadge(), or navigator.setAppBadge(0). Prefer clearAppBadge() when your only intent is to remove the badge.
Often no. App badges usually appear on installed PWA / dock / home-screen icons. Desktop demos may resolve without a visible badge — that is expected.

Next: share()

Learn how to open the native share sheet with navigator.share().

share() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Navigator sendBeacon() Method JavaScript Navigator share() Method