This specification defines an API allowing web applications to set an application-wide badge, shown in an operating-system-specific place associated with the application (such as the shelf or home screen), for the purpose of notifying the user when the state of the application has changed (e.g., when new messages have arrived), without showing a more heavyweight notification.

This specification is currently a work in progress. Implementors should not expose the API surface to the open web.

Usage examples

The following example shows how an email application might set a badge showing the unread count, which is updated whenever the client polls for mail from the server.

        async function pollForMail() {
          // ... Fetch unread mail from server. ...

          // Set the app icon badge. If getUnreadCount() returns 0, this is
          // equivalent to Badge.clear().
          Badge.set(getUnreadCount());
        }
      

The next example shows how a game might show when it is the player's turn.

        function showPlayerTurn(playerTurnId) {
          if (playerTurnId == localPlayerId)
            Badge.set();
          else
            Badge.clear();
        }
      

Badge model

There is a single global badge associated with each web application. At any time, the application's badge is set to one of the following values:

The user agent MUST initialize each application's badge to nothing. The user agent MAY reset an application's badge to nothing at its discretion (for example, when the system is restarted).

If the application's badge is nothing, the badge is said to be "cleared". Otherwise, it is said to be "set".

Badge display

When the application is installed and the application's flag is set, the user agent SHOULD display the application's badge alongside the symbolic representation of the application in the user's operating system (for example, as a small overlay on top of the application's icon).

The special value flag indicates that the badge is set, but contains no specific data. In this case, the user agent SHOULD show an indicator with a non-specific symbol (such as a coloured circle).

The user agent MAY simplify or degrade the data in any way. For example, a large integer may be saturated (for example, as "99+"). The font and formatting are entirely at the user agent's discretion. The user agent MAY ignore the data, and merely show a marker when the status is set.

Badge interface

        [Exposed=(Window, Worker)]
        interface Badge {
          static void set(optional [EnforceRange] unsigned long long contents);
          static void clear();
        };
      

The Badge interface provides methods for setting and clearing the application badge indicator.

This section is not clear about which web application is associated with a particular context. In particular, when called from a service worker whose scope is outside of the app manifest scope, the web application may be ambiguous.

set() method

When the set() method is called with argument contents, run the following steps:

  1. If contents is omitted, set the application's badge to flag.
  2. If contents is 0, set the application's badge to nothing.
  3. Else, set the application's badge to contents.
It is a bit weird that set(0) clears the badge, while set() sets it to flag. This is designed so that the above example code for setting the unread count will automatically clear the badge when the unread count is 0. But it could be a bit unintuitive.

clear() method

When the clear() method is called, set the application's badge to nothing.

Dependencies

TypeError is defined by [[!ECMASCRIPT]].