Missed the action at the 2018 Chrome Dev Summit? Catch up with our playlist on the Google Chrome Developers channel on YouTube. Watch now.

Badging for App Icons

What is the Badging API?

Examples of badges on launch icons across different platforms.

The Badging API is a new web platform API that 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 it can be used 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, there’s no special permission needed to use them.

Read explainer

Suggested use cases for the badging API

Examples of sites that may use this API include:

  • Chat, email and social apps, to signal that new messages have arrived, or 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 In Progress
3. Gather feedback & iterate on design In progress
4. Origin trial Not started
5. Launch Not started

How to use the badging API

To use the badging API, your web app needs to meet Chrome’s installability criteria, and a user must add it to their home screen.

The Badge interface is a member object on Window and Worker. It contains two methods:

  • set([number]): Sets the app's badge. If a value is provided, set the badge to the provided value.
  • clear(): Removes app's badge.
// In a web page
const unreadCount = 24;
window.Badge.set(unreadCount);

// In a service worker
self.addEventListener('sync', () => {
  self.Badge.set(getUnreadCount());
});

Badge.set() and Badge.clear() can be called from either a foreground page or potentially 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, Android only shows a white dot, instead of the 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?

Helpful Links

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

Send feedback about...