Skip to Content
Platform.Ontology

Badging API

Shows a number or dot on an installed app icon.

Works without askingNotifications and backgroundNotificationsWeb browsersWhile you use it

In one line

Can show a number or dot on the icon of an installed web app

Shows a number or dot on an installed app icon.

Puts an unread count on the app icon of an installed web app. No prompt on desktop, but iOS needs notification permission and an installed app. It shows the person that the app has attention to give.

What it can and can't do

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

It can

  • Show an unread count or dot on the app icon
  • Update the count while the app is open or when a push arrives
  • Clear the count when you open the item

It cannot

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

How it differs between platforms: Chrome and Edge on desktop need no pop up. iPhone needs a Home Screen web app plus allowed notifications. Firefox does not support it.

Browser support

BrowserStatusFirst versionReleasedNote
ChromeSupported812020-04-07Installed PWAs
EdgeSupported812020-04-13None
FirefoxNot supportedNot availableNot listedNone
SafariSupported172023-09-18macOS Dock web apps
Safari on iPhoneSupported16.42023-03-27Home Screen web apps with notification permission
Chrome on AndroidSupported812020-04-07BCD lists no support; agent research says otherwise
Samsung InternetSupported13.02020-12-02BCD lists no support; agent research says otherwise

How a site asks for it

APInavigator.setAppBadge(n), clearAppBadge()
Permission namenotifications (iOS)
Browser compat keysapi.Navigator.setAppBadge
How access is grantedinstall
What the user seesNo prompt on desktop Chrome and Edge; iOS requires Home Screen web app plus granted notifications.
Needs a secure context (HTTPS)Yes
Needs a user gestureNo
How long it lastsPersists until cleared
How to take it backClear or uninstall
Inside an iframeNot delegated

Typical flow

  1. Install the PWA
  2. Call setAppBadge(count)
  3. OS draws badge on icon

Data you get

What comes back: Badge count
Shape: integer
How often: on call

FieldTypeUnitRangePrecision
countintegernumber0 to 4,294,967,295 (unsigned long)1

Technical limits

  • Needs installed app
  • Count only, no text

The story

What it is

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

For you

You see a number or dot on the app icon in your dock or home screen, like unread chats. It tells you something is waiting without a pop up.

For makers

Makers use the badge to pull people back to the app. A small count can raise return visits. It is only for installed web apps, and works with push messages.

Where you see it

TypeExampleApps
messagingA web chat app installed on your laptop shows a red 3 on its icon when three new messages arrive.Slack web app, Telegram Web
productivityA web mail app shows the count of unread emails on its dock icon.Gmail
gamesA browser game shows a dot when your turn arrives in an online board game.None named
shoppingA store web app shows a dot when your order ships or a deal drops.None named
socialA social web app shows a number for new replies and follows.X, Bluesky
productivityA task web app shows how many tasks are due today.Todoist
newsA news web app shows how many breaking stories you have not read.None named

Risks

  • Nagging counts
  • Only installed apps

What the platform says

  • web.dev: Badging API. Installed web apps can set a badge on their icon to show new items, such as unread messages.

Good uses and abuse

Legitimate uses

  • Unread counts

Known abuse

  • Attention nagging

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-04, Chrome 81: Badging ships on desktop
  • 2023-03, Safari on iPhone 16.4: Badging for Home Screen web apps
  • 2023-09, Safari 17: Badging for web apps added to Dock
  • Notifications. Can show messages on your screen outside the browser tab, once you tap Allow

Sources

How well checked: Based on official documentation.

On this page