| CARVIEW |
Badging API
More details about this document
- This version:
- https://www.w3.org/TR/2025/WD-badging-20251006/
- Latest published version:
- https://www.w3.org/TR/badging/
- Latest editor's draft:
- https://w3c.github.io/badging/
- History:
- https://www.w3.org/standards/history/badging/
- Commit history
- Editors:
- Jay Harris (Brave Software, Inc.)
- Marcos Cáceres (Apple Inc.)
- Diego González (Microsoft)
- Former editor:
- Matt Giuca (Google Inc.) - Until
- Feedback:
- GitHub w3c/badging (pull requests, new issue, open issues)
Copyright © 2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
Abstract
This specification defines an API that allows installed web applications to set an application badge, which is usually shown alongside the application's icon on the device's home screen or application dock.
Status of This Document
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index.
This is a work in progress.
This document was published by the Web Applications Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than a work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent that the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 18 August 2025 W3C Process Document.
This section is non-normative.
Badges can contribute to notification fatigue for some users. As such, authors need to reserve badges for states that truly merit user attention or action; avoid using them for marketing or engagement gimmicks.
Avoid rapidly changing values that increase distraction or cognitive load.
To support users who do not perceive badges, or have disabled them at the system level, authors are encouraged to present the same state within application UI using accessible patterns (e.g., clearly labeled in-app status indicators).
This section is non-normative.
async function updateMailBadge() {
// Check if the API is supported.
if (!navigator.setAppBadge) return;
const unreadCount = await getUnreadMailCount();
// Try to set the app badge.
try {
await navigator.setAppBadge(unreadCount);
} catch (e) {
// The badge is not supported, or the user has prevented the app
// from setting a badge.
}
}The badge might show up on the application's icon in the operating system. If multiple API calls within the same application set or clear a badge, the most recent one takes effect, and may continue being seen even after an application is closed.
async function showPlayerTurn(playerTurnId) {
if (playerTurnId === localPlayerId)
await navigator.setAppBadge();
else
await navigator.clearAppBadge();
}
On some operating systems setting a badge can require
permission from the user. In this case, a developer need to query the
"notifications" permissions status before setting a
badge. If the permission is not granted, the developer will need to
prompt for permission via the
Notification.requestPermission().
async function checkPermission() {
permission = await navigator.permissions.query({
name: "notifications",
});
const button = document.getElementById("permission-button");
if (permission.state === "prompt") {
// Prompt the user to grant permission.
button.hidden = false;
button.addEventListener("click", async () => {
await Notification.requestPermission();
checkPermission();
}, { once: true });
return;
}
button.hidden = true;
}A badge is intended as a mechanism for installed web applications to notify the user that there is some new activity that might require their attention, or as a way of indicating a small amount of information, such as an unread count.
A badge can have one of the following values:
- The special value "nothing":
- Indicates that there is no badge currently set. When a badge has this value, no visual indicator should be displayed to the user.
- The special value "flag":
- Indicates that the badge is set and should be displayed to the user, but contains no specific numerical value. This is distinct from "nothing" in that a visual indicator should be shown to the user to indicate the presence of the badge.
- A number value:
-
Indicates that the badge is set to a numerical value
greater than
0.
An installed web application has an associated badge, which is initialized to "nothing". The operating system stores and manages the badge value, with the user agent acting as an intermediary to communicate badge changes to the OS.
The user agent MAY (re)set an application's badge to "nothing" at its discretion (for example, following system conventions).
When the application's badge is set, the user agent or operating system SHOULD display the application's badge alongside the primary iconic representation of the application in the user's operating system (for example, as a small overlay on top of the application's icon on the home screen on a device).
A user agent MAY require express permission from the user to set the badge. When a user agent requires such permission, it SHOULD tie the permission grant to the "notifications" permission.
When the badge is set to "flag", the user agent or operating system SHOULD display an indicator with a non-specific symbol (for example, a colored circle). If the platform does not support displaying a "flag" badge, the user agent SHOULD display the badge using the closest available representation that indicates the presence of a badge (e.g., the value "1"), rather than clearing the badge entirely.
When a badge's value is set to "nothing", the user agent or operating system SHOULD clear the badge by no longer displaying it.
When the badge is set to a number, the user agent or operating system:
- SHOULD format and display the number according to the user's font and formatting preferences. For example, as a number in a circle on top of the application's icon on the home screen on a device.
- MAY simplify or degrade a badge's number value in any way that matches the platform's conventions for representing numbers in a badge. For example, a platform might choose to display a badge with a value of '100' as '99+'.
- SHOULD localize the number according to the user's locale preferences. For example, the value '7' should be displayed as '7' in the locale 'en' (English) but as '٧' in 'ar' (Arabic).
- MAY treat a number value as "flag", or whatever representation is most appropriate for the platform, if the platform does not support displaying numbers in a badge. Similarly, if the platform does not support "flag" badges, it MAY represent "flag" using a number or other appropriate visual indicator, but MUST NOT clear the badge when "flag" is requested.
Different operating systems have varying capabilities for displaying badges. The ultimate display behavior is controlled by the operating system and might be further modified by user settings or system conventions. When communicating badge information to the operating system, user agents SHOULD preserve the semantic intent of the badge request:
- When the operating system does not support "flag" badges, the user agent SHOULD communicate to the OS using the closest available representation that conveys the presence of a badge (such as the number "1" or generic symbol) rather than communicating a request to clear the badge.
- When the operating system does not support number badges, the user agent MAY communicate the badge to the OS as a "flag" representation.
- The user agent MUST NOT interpret a request to set a "flag" as equivalent to clearing the badge when communicating with the operating system.
WebIDL[SecureContext]
interface mixin NavigatorBadge {
Promise<undefined> setAppBadge(
optional [EnforceRange] unsigned long long contents
);
Promise<undefined> clearAppBadge();
};
Navigator includes NavigatorBadge;
WorkerNavigator includes NavigatorBadge;
User agents that never display application badges SHOULD NOT
include NavigatorBadge.
When the setAppBadge() method is called, the user
agent MUST set the application badge of this to value of the
contents argument.
When the clearAppBadge() method is called, the user
agent MUST set the application badge of this to 0.
To set the application badge of platform object
context to an optional unsigned long long
contents value:
- Let global be context's relevant global object.
- If global is a
Windowobject, then:- Let document be global's associated
Document. - If document is not fully active, return a promise rejected with a "
InvalidStateError"DOMException. - If document's relevant settings object's origin is
not same origin-domain with this's relevant settings object's top-level origin, return a promise rejected with a "
SecurityError"DOMException.
- Let document be global's associated
- Let promise be a new promise.
- In parallel:
- If the user agent requires express permission to
set the application badge, then:
- Let permissionState be the result of getting the current permission state with "notifications".
- If permissionState is not "
granted", queue a global task on the user interaction task source given global to reject promise with aNotAllowedErrorand terminate this algorithm.
- Switching on contents, if it happens to be the case that:
- Queue a global task on the DOM manipulation task source
given global to resolve promise with
undefined.
- If the user agent requires express permission to
set the application badge, then:
- Return promise.
The API is write-only by design. There is no way for a site to read back the value of a badge that was previously set, to ensure that the application badge cannot be used as a storage or fingerprinting mechanism.
The user agent or operating system MAY clear a badge at its discretion, and to follow any system conventions (for example, when the system is reset).
User agents MAY rate-limit badge setting or clearing the application badge to prevent distracting animations and reduce resource usage. However, user agents SHOULD generally leave rate limiting to the operating system, as it is in a better position to determine appropriate throttling based on system load, user preferences, and accessibility considerations.
Application badges convey status that can require the user's attention. Because badges are often presented outside the web content area (for example, on an app icon in the dock), user agents need to ensure that the information remains accessible and controllable through platform accessibility features and user preferences.
User agents SHOULD expose the current value (including "flag" vs. number) through platform accessibility APIs so that assistive technologies can present it on demand (for example, when the user focuses the application icon).
User agents SHOULD NOT automatically announce badge changes; instead, they SHOULD follow platform conventions that avoid unsolicited interruptions.
This section is non-normative.
As badges are typically drawn by the underlying platform, visual affordances are typically handled there. Nevertheless, user agents and platforms need to consider:
- Do not rely on color alone to convey meaning (provide text or an accessible name).
- Ensure sufficient non-text contrast between badge glyph and background.
- Use sizing that remains legible across system font/scale settings.
- Honor high-contrast / forced-colors and dark mode preferences where applicable.
- If animating badge changes, honor reduced-motion preferences and avoid flashing effects.
User agents SHOULD integrate with platform accessibility settings and themes.
User agents SHOULD reflect OS-level per-application badge preferences (for example, when the operating system disables badges for an app).
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
- [appmanifest]
- Web Application Manifest. Marcos Caceres; Kenneth Christiansen; Diego Gonzalez-Zuniga; Daniel Murphy; Christian Liebel. W3C. 3 September 2025. W3C Working Draft. URL: https://www.w3.org/TR/appmanifest/
- [html]
- HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
- [infra]
- Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
- [notifications]
- Notifications API Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://notifications.spec.whatwg.org/
- [permissions]
- Permissions. Marcos Caceres; Mike Taylor. W3C. 26 September 2025. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
- [WEBIDL]
- Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: