What is the Badging API?
The Badging API allows installed web apps to set an application-wide badge, shown in an operating-system-specific place associated with the application (such as the shelf or home screen).
Badging makes it easy to subtly notify the user that there is some new activity that might require their attention, or to indicate a small amount of information, such as an unread count.
Badges tend to be more user-friendly than notifications, and can be updated with a much higher frequency, since they don't interrupt the user. And, because they don't interrupt the user, they don't need the user's permission.
Possible use cases
Examples of sites that may use this API include:
- Chat, email, and social apps, to signal that new messages have arrived, or to show the number of unread items.
- Productivity apps, to signal that a long-running background task (such as rendering an image or video) has completed.
- Games, to signal that a player action is required (e.g., in Chess, when it is the player's turn).
|1. Create explainer||Complete|
|2. Create initial draft of specification||Complete|
|3. Gather feedback & iterate on design||In progress|
|4. Origin trial||In progress|
|5. Launch||Not started|
- Using Chrome 73 or later on Windows or Mac, open the Badging API demo.
- When prompted, click Install to install the app, or use the Chrome menu to install it.
- Open it as an installed PWA. Note, it must be running as an installed PWA (in your task bar or dock).
- Click the Set or Clear button to set or clear the badge from the app icon. You can also provide a number for the Badge value.
While the Badging API in Chrome requires an installed app with an icon that can actually be badged, you shouldn't make calls to the Badging API dependent on the install state. The Badging API can apply to anywhere a browser might want to show a badge, so developers shouldn't make any assumptions about situations where the browser will display them. Just call the API when it exists. If it works, it works. If not, it simply doesn't.
How to use the Badging API
Starting in Chrome 73, the Badging API is available as an origin trial for Windows (7+) and macOS.
Caution: Android is not supported because it requires you to show a notification, though this may change in the future. Chrome OS support is pending implementation of badging on the platform.
Register for the origin trial
Origin trials allow you to try new features and give feedback on their usability, practicality, and effectiveness to the web standards community. For more information, see the Origin Trials Guide for Web Developers. To sign up for this or another origin trial, visit the registration page.
- Request a token for your origin.
- Add the token to your pages. There are two ways to do that:
- Add an
<meta>tag to the head of each page. For example, this may look something like:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
- If you can configure your server, you can also add the token
Origin-TrialHTTP header. The resulting response header should look something like:
- Add an
Alternatives to the origin trial
If you want to experiment with the Badging API locally, without an origin trial,
#enable-experimental-web-platform-features flag in
Using the Badging API during the origin trial
During the origin trial, the API will be available via
window.ExperimentalBadge. The code below is based on the current design,
and will change before it lands in the browser as a standardized API.
To use the Badging API, your web app needs to meet Chrome's installability criteria, and users must add it to their home screens.
ExperimentalBadge interface is a member object on
window. It contains
set([number]): Sets the app's badge. If a value is provided, set the badge to the provided value otherwise, display a plain white dot (or other flag as appropriate to the platform).
clear(): Removes app's badge.
// In a web page
const unreadCount = 24;
ExperimentalBadge.clear() can be called from
a foreground page, or potentially in the future, a service worker. In either
case, it affects the whole app, not just the current page.
In some cases, the OS may not allow the exact representation of the badge, in this case, the browser will attempt to provide the best representation for that device. For example, while the Badging API isn't supported on Android, Android only ever shows a dot instead of a numeric value.
Don't assume anything about how the user agent wants to display the badge.
Some user agents may take a number like "4000" and rewrite it as
"99+". If you saturate the badge yourself (for example by setting it to "99")
then the "+" won't appear. No matter the actual number, just set
Badge.set(unreadCount) and let the user agent deal with displaying it
The Chrome team wants to hear about your experiences with the Badging API.
Tell us about the API design
Is there something about the API that doesn't work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model?
- File a spec issue on the Badging API GitHub repo, or add your thoughts to an existing issue.
Problem with the implementation?
Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?
- File a bug at https://new.crbug.com. Be sure to include as much detail
as you can, simple instructions for reproducing, and set
UI>Browser>WebAppInstalls. Glitch works great for sharing quick and easy repros.
Planning to use the API?
Planning to use Badging API on your site? Your public support helps the Chrome team to prioritize features, and shows other browser vendors how critical it is to support them.
- Send a Tweet to @ChromiumDev tagged with
#badgingapiand let us know where and how you're using it.