Skip to Content
Platform.Ontology

Badging API

Shows a number or dot on the app icon.

Does something on your deviceHome screen and system linksNotification surfaceWeb browsersWhile you use it

In one line

Can show a number or dot on an installed app's icon, but can't check it

Shows a number or dot on the app icon.

Alerts the person to unread items without a notification. Cannot read badge state.

What it can and can't do

What the user does: You install the web app and, on iPhone, allow notifications

It can

  • Show an unread count or dot on the app icon
  • Update it when something new arrives
  • Clear it once you open the item

It cannot

  • Work for a site that is not installed as an app
  • Check what number is already showing
  • Work in Firefox
  • Work on iPhone without notification permission

How it differs between platforms: Chrome, Edge and Safari support it for installed apps. iPhone also needs notification permission. Firefox does not.

Browser support

BrowserStatusFirst versionReleasedNote
ChromeSupported812020-04-07Windows and macOS since Chrome 81. ChromeOS since Chrome 91. Linux offers no universal badging API on the operating system level.
EdgeSupported812020-04-13Windows and macOS since Edge 81. ChromeOS since Edge 91. Linux offers no universal badging API on the operating system level.
FirefoxNot supportedNot availableNot listedNone
SafariSupported172023-09-18Badging is supported for installed web apps on macOS Sonoma and higher. Passing <code>0</code> as an argument will clear the badge instead of displaying an unnu
Safari on iPhoneSupported16.42023-03-27Badging is supported for web apps saved to the home screen. Passing <code>0</code> as an argument will clear the badge instead of displaying an unnumbered dot.
Chrome on AndroidNot supportedNot availableNot listedNone
Samsung InternetNot supportedNot availableNot listedNone

How a site asks for it

APInavigator.setAppBadge(count), clearAppBadge()
Browser compat keysapi.Navigator.setAppBadge
How access is grantedinstall
What the user seesNone; needs installed app and sometimes notification permission
Needs a secure context (HTTPS)Yes
Needs a user gestureNo
How long it lastsPer origin
How to take it backSite settings
Inside an iframeSame as top level; cross-origin iframes need a permissions policy where listed

Typical flow

  1. Call the API
  2. Browser applies its access rules
  3. Page receives the result

Data you get

What comes back: Shows a number or dot on the app icon.
Shape: object
How often: on demand

FieldTypeUnitRangePrecision
countintegerNone0 to 2^53-1; 0 clearsicon shows digits up to OS limit

Technical limits

  • No badge on Chrome Android
  • iOS needs web push permission
  • Installed app only

The story

What it is

An installed web app can show a number or dot on its app icon.

For you

You see a small number or dot on the app icon in the dock or taskbar. It tells you there are new items. There is no pop up to dismiss.

For makers

Makers use it to draw you back. A count on the icon is a low cost nudge that works with push messages. It only works for installed web apps.

Where you see it

TypeExampleApps
messagingA chat web app installed on your PC shows how many unread chats you have.Slack, Telegram Web
productivityA web mail app shows a count of unread mail on its icon.Gmail
gamesA browser game shows a dot when a turn or reward is waiting.None named
socialA social web app shows the number of new replies.X
shoppingA store app shows a dot when a deal or order update arrives.None named
productivityA task app shows how many tasks are due.Todoist
newsA news app shows unread top stories.None named

Risks

  • Nagging counts
  • Only installed apps

What the platform says

  • web.dev: Badging API. Installed web apps can show a badge on the icon to say there is something new.

Good uses and abuse

Legitimate uses

  • Chat and mail apps

Known abuse

  • Nag badges

Scores

ScoreValueMeaning
Sensitivity1 of 5How revealing the data is
Utility3 of 5How useful it is to honest apps
Friction1 of 5How much the user has to do
Fingerprint bitsNot ratedRough identifying entropy, when known

History

  • 2020-05, Chrome 81: Badging API on desktop
  • 2023-09, Safari 17: macOS Safari (iOS 16.4)

Sources

How well checked: Checked against real behavior.

On this page