Badging API

Web developers frequently update document favicons or titles in order to indicate status. The Badging API provides a more elegant way to show status, by providing a method which has meaning to the user agent and can therefore be displayed in a way that matches the rest of the UI.

There are two types of badges:

• Document badges, which are typically shown in the browser tab near or on the page icon.
• App badges, which are associated with the icon of an installed web app. These may display on the app icon in the dock, shelf, or home screen depending on the device in use.

A badge can have one of three possible values, which are set internally:

nothing

Indicating that no badge is currently set. A badge can be in this state due to it being cleared by the application, or being reset by the user agent.

flag

Indicating that the badge is set, but has no specific data to display. A badge will be in this state if the application has set a badge, but has not passed any value to the method.

an integer

A value passed when setting the badge. This value will never be 0, passing a value of 0 when setting a badge will cause the user agent to clear the badge by setting it to nothing.

A badge is set with the methods setAppBadge() (for installed apps), or setClientBadge() (for documents). If no parameters are passed to these methods then the badge value is flag. The user agent will display its notification badge, for example, a colored circle on the icon.

These methods can also be passed a parameter contents, which should be a number. This will then be displayed as part of the badge. User agents may change this value in some way. For example, if you pass a very large number such as 4000, the user agent may display this as 99+ in the badge. User agents may also ignore this data and display a marker instead.

Badges are cleared with the clearAppBadge() and clearClientBadge() methods. These do not take any parameters and set the badge to the value nothing. Additionally, passing a value of 0 to setAppBadge() or setClientBadge() will set the badge to nothing and clear the badge.

None.

Navigator.setAppBadge()

Sets a badge on the icon associated with this app.

Navigator.clearAppBadge()

Clears the badge on the icon associated with this app.

Navigator.setClientBadge()

Sets a badge on the icon associated with the current document.

Navigator.clearClearClientBadge()

Clears the badge on the icon associated with the current document.

WorkerNavigator.setAppBadge()

Sets a badge on the icon associated with this app.

WorkerNavigator.clearAppBadge()

Clears the badge on the icon associated with this app.

WorkerNavigator.setClientBadge()

Sets a badge on the icon associated with the current document.

WorkerNavigator.clearClearClientBadge()

Clears the badge on the icon associated with the current document.

To set a notification badge on the current document with no value:

navigator.setClientBadge();

To clear a notification badge on the current document:

navigator.clearClientBadge();

To set a notification badge on the current app with a value of 12:

navigator.setAppBadge(12);

• Badging for app icons
• Badging API Explainer