Badging API
Shows a number or dot on the app icon.
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
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 81 | 2020-04-07 | Windows and macOS since Chrome 81. ChromeOS since Chrome 91. Linux offers no universal badging API on the operating system level. |
| Edge | Supported | 81 | 2020-04-13 | Windows and macOS since Edge 81. ChromeOS since Edge 91. Linux offers no universal badging API on the operating system level. |
| Firefox | Not supported | Not available | Not listed | None |
| Safari | Supported | 17 | 2023-09-18 | Badging 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 iPhone | Supported | 16.4 | 2023-03-27 | Badging 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 Android | Not supported | Not available | Not listed | None |
| Samsung Internet | Not supported | Not available | Not listed | None |
How a site asks for it
| API | navigator.setAppBadge(count), clearAppBadge() |
| Browser compat keys | api.Navigator.setAppBadge |
| How access is granted | install |
| What the user sees | None; needs installed app and sometimes notification permission |
| Needs a secure context (HTTPS) | Yes |
| Needs a user gesture | No |
| How long it lasts | Per origin |
| How to take it back | Site settings |
| Inside an iframe | Same as top level; cross-origin iframes need a permissions policy where listed |
Typical flow
- Call the API
- Browser applies its access rules
- 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
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
count | integer | None | 0 to 2^53-1; 0 clears | icon 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
| Type | Example | Apps |
|---|---|---|
| messaging | A chat web app installed on your PC shows how many unread chats you have. | Slack, Telegram Web |
| productivity | A web mail app shows a count of unread mail on its icon. | Gmail |
| games | A browser game shows a dot when a turn or reward is waiting. | None named |
| social | A social web app shows the number of new replies. | X |
| shopping | A store app shows a dot when a deal or order update arrives. | None named |
| productivity | A task app shows how many tasks are due. | Todoist |
| news | A 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
| 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-05, Chrome 81: Badging API on desktop
- 2023-09, Safari 17: macOS Safari (iOS 16.4)
Sources
How well checked: Checked against real behavior.