Badging API
Shows a number or dot on an installed app icon.
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
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 81 | 2020-04-07 | Installed PWAs |
| Edge | Supported | 81 | 2020-04-13 | None |
| Firefox | Not supported | Not available | Not listed | None |
| Safari | Supported | 17 | 2023-09-18 | macOS Dock web apps |
| Safari on iPhone | Supported | 16.4 | 2023-03-27 | Home Screen web apps with notification permission |
| Chrome on Android | Supported | 81 | 2020-04-07 | BCD lists no support; agent research says otherwise |
| Samsung Internet | Supported | 13.0 | 2020-12-02 | BCD lists no support; agent research says otherwise |
How a site asks for it
| API | navigator.setAppBadge(n), clearAppBadge() |
| Permission name | notifications (iOS) |
| Browser compat keys | api.Navigator.setAppBadge |
| How access is granted | install |
| What the user sees | No prompt on desktop Chrome and Edge; iOS requires Home Screen web app plus granted notifications. |
| Needs a secure context (HTTPS) | Yes |
| Needs a user gesture | No |
| How long it lasts | Persists until cleared |
| How to take it back | Clear or uninstall |
| Inside an iframe | Not delegated |
Typical flow
- Install the PWA
- Call setAppBadge(count)
- OS draws badge on icon
Data you get
What comes back: Badge count
Shape: integer
How often: on call
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
count | integer | number | 0 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
| Type | Example | Apps |
|---|---|---|
| messaging | A web chat app installed on your laptop shows a red 3 on its icon when three new messages arrive. | Slack web app, Telegram Web |
| productivity | A web mail app shows the count of unread emails on its dock icon. | Gmail |
| games | A browser game shows a dot when your turn arrives in an online board game. | None named |
| shopping | A store web app shows a dot when your order ships or a deal drops. | None named |
| social | A social web app shows a number for new replies and follows. | X, Bluesky |
| productivity | A task web app shows how many tasks are due today. | Todoist |
| news | A 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
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 1 of 5 | How revealing the data is |
| Utility | 3 of 5 | How useful it is to honest apps |
| Friction | 1 of 5 | How much the user has to do |
| Fingerprint bits | Not rated | Rough 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
Related capabilities
Related
- Notifications. Can show messages on your screen outside the browser tab, once you tap Allow
Sources
How well checked: Based on official documentation.