Can’t make the #ChromeDevSummit this year? Catch all the content (and more!) on the livestream, or join your peers for a CDS Extended event at a hosted location nearby. To learn more, check out the Chrome Dev Summit 2019 website.

Badging for App Icons

What is the Badging API?

Example of Twitter with eight notifications and another app showing a flag type badge.

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.

Read explainer

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).

Current status

Step Status
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

See it in action

  1. Using Chrome 73 or later on Windows or Mac, open the Badging API demo.
  2. When prompted, click Install to install the app, or use the Chrome menu to install it.
  3. Open it as an installed PWA. Note, it must be running as an installed PWA (in your task bar or dock).
  4. 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.

How to use the Badging API

Starting in Chrome 73, the Badging API is available as an origin trial for Windows (7+) and macOS.

Origin trials allow you to try out new features and give feedback on usability, practicality, and effectiveness to us, and the web standards community. For more information, see the Origin Trials Guide for Web Developers.

Register for the origin trial

  1. Request a token for your origin.
  2. Add the token to your pages, there are two ways to provide this token on any pages in your origin:
    • Add an origin-trial <meta> tag to the head of any 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 provide the token on pages using an Origin-Trial HTTP header. The resulting response header should look something like: Origin-Trial: TOKEN_GOES_HERE

Alternatives to the origin trial

If you want to experiment with the Badging API locally, without an origin trial, enable the #enable-experimental-web-platform-features flag in chrome://flags.

Using the Badging API during the origin trial

To use the Badging API, your web app needs to meet Chrome’s installability criteria, and users must add it to their home screens.

The ExperimentalBadge interface is a member object on window. It contains two methods:

  • 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.

For example:

// In a web page
const unreadCount = 24;
window.ExperimentalBadge.set(unreadCount);

ExperimentalBadge.set() and 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.

Feedback

We need your help to ensure that the Badging API works in a way that meets your needs and that we’re not missing any key scenarios.

We’re also interested to hear how you plan to use the Badging API:

  • Have an idea for a use case or an idea where you'd use it?
  • Do you plan to use this?
  • Like it, and want to show your support?

Share your thoughts on the Badging API WICG Discourse discussion.

Was this page helpful?
Yes
What was the best thing about this page?
It helped me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had the information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had accurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was easy to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
No
What was the worst thing about this page?
It didn't help me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was missing information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had inaccurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was hard to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.

Helpful Links

rss_feed Subscribe to our RSS or Atom feed and get the latest updates in your favorite feed reader!