Wiki · Concept · Last reviewed June 25, 2026

Badging API

The Badging API lets an installed web application set or clear a small badge associated with its app icon, creating a quiet but persistent claim on user attention.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser API, badges, progressive web apps, service workers, attention, agents

Definition

The Badging API is a web-platform API for setting an application badge, usually shown with an installed web application's icon on an operating-system home screen, dock, shelf, or taskbar. The W3C Badging API technical report is a Working Draft, and the draft says it is intended for installed web applications that need to show new activity or a small amount of status information, such as an unread count.

The core distinction is quietness. A badge says that state has changed without opening a notification center item, vibrating the device, displaying body text, or requiring immediate action. That makes it easy to underestimate. A badge is still an attention claim, and in agent systems it can be a visible result of autonomous classification, prioritization, or background work.

The API is not related to educational or credential "badges." It is about a browser and operating system presenting a small application-status indicator for a web app.

Snapshot

Current Context

As of June 25, 2026, the W3C Badging API latest published technical report was a Working Draft dated April 27, 2026, not a W3C Recommendation. The draft says it is inappropriate to cite the document as anything other than a work in progress, so compliance language should avoid claiming that badging is a settled cross-browser standard.

Implementation remains platform-specific. MDN marks the Badging API as limited availability and secure-context only, while noting worker availability. Chrome's developer documentation describes the API for installed web apps and warns that user agents or operating systems may rewrite numeric values, such as displaying a large count as 99+ or as a dot. WebKit's iOS and iPadOS 16.4 announcement says support is limited to home-screen web apps and that the badge appears only if notification permission has been granted; it also says the user's OS-level badge preference is not exposed back to the web app.

For browser-agent design, that means badging should be treated as a best-effort presentation layer. The governed state must live in the app or audit record, because the badge may be unsupported, rewritten, cleared, hidden by user preference, or inaccessible to some users.

Boundary Tests

Not the Notifications API. The Notifications API displays system notifications with titles, bodies, icons, actions, click events, and permission prompts. The Badging API sets a compact app-status indicator.

Not the Push API. Push API concerns delivery of server-originated messages to a service worker. A push event can update a badge, but a badge update alone is not the same as push delivery or a user-visible notification requirement.

Not a service worker lifecycle. Service Workers can call badging methods from worker contexts when supported, but they govern event handling, caching, fetch interception, and background execution, not the meaning of the badge.

Not a web app manifest. The Web App Manifest supplies app identity, icons, display mode, and install metadata. The Badging API modifies status on the app surface after installation.

Not an audit trail. A badge may persist after an app closes, but it is not a durable record of the triggering event, agent decision, source data, or user acknowledgment.

How It Works

The main methods are navigator.setAppBadge() and navigator.clearAppBadge(). Passing a positive number to setAppBadge() requests a numeric badge. Calling it without a value requests a flag-style badge. Passing 0 clears the badge by setting it to nothing. clearAppBadge() also clears the badge. The W3C draft defines both methods as returning promises.

The draft defines the badge model as nothing, flag, or number. The operating system stores and manages the badge value, while the user agent communicates badge changes to the OS. The user agent or operating system may clear a badge at its discretion and may rate-limit setting or clearing.

Display is not exact. The draft allows the user agent or operating system to localize, simplify, degrade, or substitute badge representation according to platform conventions. A numeric request can be shown as a different number, a capped value, a dot, or another badge representation.

The API is secure-context only. In a window context, the draft rejects calls if the document is not fully active or if the document origin is not same-origin-domain with the top-level origin. When a user agent requires express permission for badging, the draft ties that permission check to the notifications permission and rejects the promise if permission is not granted.

Worker exposure matters for background behavior. The draft includes WorkerNavigator, and browser-vendor documentation describes using badging from service workers, for example after background sync or push handling. That does not make the badge a reliable background channel; support and permission behavior still depend on the browser and operating system.

Agent Context

For AI Browsers and Computer Use, badging matters because an agent can change the user's environment without opening a page. A mail assistant, scheduling agent, shopping monitor, claims workflow, learning system, or workplace dashboard can leave a count or flag on an installed web app after background work.

Badging sits near Notifications API, Push API, Service Workers, and Web App Manifest, but it is not the same layer. Push can deliver data, a service worker can run background code, a notification can interrupt, a manifest can define app identity, and a badge can persist as a quiet reminder. A governed agent design should treat those as separate events.

The agent-specific risk is status ambiguity. A badge count might represent unread messages, generated recommendations, failed automations, overdue reviews, fraud flags, queued tasks, or marketing prompts. If an agent sets the badge after ranking or classifying work, the app should expose a human-readable explanation of the count inside the application.

Governance Use

Governance should treat a badge as user-facing output, especially when an agent sets it after interpreting a task, classifying a priority, or summarizing unread work. A badge can steer a user's next action, change the perceived urgency of a queue, or make one app look more important than another. The W3C draft explicitly warns against using badges for marketing or engagement gimmicks and against rapidly changing values that increase distraction or cognitive load.

For high-impact workflows, a badge should not be the only evidence of a deadline, alert, adverse decision, or required approval. The application should preserve a readable in-app state, because users may disable badges, miss them, use a platform that does not support them, or use assistive technology that does not perceive the operating-system badge.

Accessibility belongs in the governance record. The W3C draft says badges convey status that can require attention, should be exposed through platform accessibility APIs when supported, should not be automatically announced like an interruption, and should not rely on color alone. Product review should therefore ask what equivalent in-app status exists and how users can turn badge-driven attention off.

Limits

The Badging API is not a delivery guarantee, audit log, task queue, notification permission system, or proof that a user saw anything. Platform behavior differs, and the user agent or operating system can clear, hide, rewrite, localize, cap, or replace the requested badge presentation.

Numeric values also need care. A count can be stale, saturated, platform-rewritten, or semantically ambiguous. A badge reading "17" does not explain whether it means messages, tasks, risks, errors, unread files, or agent recommendations.

The API is also intentionally write-only. A site cannot read the current badge value back through the API, so application state cannot depend on the badge as the source of truth. The app has to store and clear its own underlying state separately.

Failure Modes

Badge-only obligation. A deadline, warning, or approval request exists only as a badge. Users who miss, disable, or cannot perceive badges have no equivalent in-app record.

Stale agent count. A background agent updates a badge after stale classification, failed synchronization, or partial task completion, making the queue look more urgent or less urgent than it is.

Engagement inflation. The badge is used to create unresolved attention rather than to communicate meaningful state, contrary to the W3C responsible-use guidance.

Permission confusion. A product assumes that notification permission, push subscription, install status, and badge display are one permission state, even though browsers and operating systems separate them differently.

Count leakage. A badge reveals sensitive status on a shared screen, dock, home screen, or taskbar, such as case count, health messages, workplace queue size, debt notices, or relationship activity.

Audit gap. The system logs that an agent task completed, but not that it changed the user's operating-system app surface by setting or clearing a badge.

Minimum Evidence Record

For agent-mediated badging, record the origin, app scope, manifest identifier or launch URL where available, triggering event, service worker registration scope if applicable, permission state when checked, prior application state, requested new badge class, timestamp, agent task identifier, user-visible reason, and clearing event. Avoid storing sensitive counts or labels beyond the audit purpose.

For high-impact applications, also record the in-app state that corresponds to the badge, the user control for disabling badge-driven attention, the platform family tested, and whether the request was accepted or rejected by the API promise. This evidence should prove why the badge changed, not merely that JavaScript called setAppBadge().

Defense Pattern

Source Discipline

Use the W3C Badging API technical report or editor's draft for the formal badge model, method definitions, permission hooks, same-origin checks, privacy considerations, security considerations, accessibility language, and responsible-use guidance. Cite it as a Working Draft unless its W3C status changes.

Use MDN for developer-facing summaries, secure-context notes, limited-availability status, and method reference pages. Use browser-vendor documentation only for platform-specific behavior, such as Chrome's installed-app expectations, Edge's PWA guidance, or WebKit's home-screen and notification-permission behavior. Do not generalize one browser's implementation to the whole web.

Spiralist Reading

Spiralism reads app badges as small public debts of attention. They do not shout, but they accumulate. A humane system uses them to keep a promise: something changed, and the user can return when ready. An extractive system uses them to keep the app unfinished in the mind.

Sources

Return to Wiki