Wiki · Concept · Last reviewed June 25, 2026

Badging API

The Badging API lets a web application set or clear a small badge associated with the document or installed app icon.

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 specification defines it as a work in progress and says the API is intended for installed web applications that need to show new activity or a small amount of status information, such as an unread count.

MDN describes the API as a quieter alternative to a more distracting notification. A badge says that state has changed; it does not open a notification center item, vibrate the device, display a body text, or require the user to act immediately. That makes it easy to underestimate. A badge is still an attention claim.

How It Works

The main methods are navigator.setAppBadge() and navigator.clearAppBadge(). Passing a number to setAppBadge() sets a numeric badge. Calling it without a value sets a flag-style badge, and passing 0 clears the badge by setting it to nothing. clearAppBadge() also clears the badge. MDN documents both methods as returning promises.

MDN marks the Badging API and its Navigator methods as limited availability and secure-context only. It also notes that the feature is available in web workers. The W3C model defines three badge states: nothing, flag, and number. The operating system stores and manages the badge value, while the user agent acts as intermediary. The user agent may also reset a badge to nothing at its discretion.

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, and Service Workers, but it is not the same layer. Push can deliver data, a service worker can run background code, a notification can interrupt, and a badge can persist as a quiet reminder. A governed agent design should treat those as separate events.

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, or use assistive technology that does not perceive the operating-system badge.

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. WebKit says that on iOS and iPadOS 16.4, Badging API support is for web apps the user has added to the home screen, and that the badge appears only after notification permission is granted. Microsoft Edge documentation presents badges and notifications together as PWA re-engagement tools, but also distinguishes badges as less interruptive.

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.

Minimum Evidence Record

For agent-mediated badging, record the origin, app scope, triggering event, service worker registration scope if applicable, prior badge value class, requested new value class, timestamp, agent task identifier, user-visible reason, and clearing event. Avoid storing sensitive counts or labels beyond the audit purpose.

Source Discipline

Use the W3C Badging specification for the formal badge model and responsible-use language. Use MDN for developer-facing method behavior, secure-context status, worker availability, and limited-availability warnings. Use browser-vendor documentation only for platform-specific behavior, such as home-screen availability or PWA integration, and do not generalize one browser's behavior 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