API in Notifications
Notification actions and badge options
Published Updated
actions adds buttons to a persistent notification and badge supplies the small monochrome
image the OS shows where the full notification does not fit, such as the Android status bar.
Both are members of the options dictionary of ServiceWorkerRegistration.showNotification(),
both are Chromium-only in shipping browsers apart from Firefox 152’s actions, and neither has
anything to do with the app-icon count set by the Badging API.
Syntax
Section titled “Syntax”registration.showNotification(title, { badge: '/icons/badge-96.png', actions: [{ action: 'reply', title: 'Reply', icon: '/icons/reply.png' }],})Notification.maxActionsactions is accepted only by showNotification(); passing a non-empty array to
new Notification() throws TypeError. Notification.maxActions is a static getter returning
the maximum number of actions the implementation supports. Support: actions in Chrome 53, Edge 18, Firefox 152;
badge in Chrome 53 and Edge 18; neither in Safari (BCD api.Notification.actions,
api.Notification.badge).
Members
Section titled “Members”| Member | Type | Meaning |
|---|---|---|
actions[].action |
string | Identifier returned as event.action in notificationclick. Required. |
actions[].title |
string | Button label. Required. |
actions[].icon |
string (URL), optional | Image shown on the button where the platform draws icons (Android; not Windows). |
actions[].navigate |
string (URL), optional | Where supported, the user agent navigates to this URL instead of firing notificationclick. Chromium ignores it. |
badge |
string (URL) | Image for the compact representation. Android masks it to a silhouette and shows it at up to 4x density, so a 96 by 96 pixel single-colour PNG with transparency is the working size. |
Chromium displays at most kMaximumActions = 2 buttons (notification.mojom,
chromium.googlesource.com) and drops the rest without error; Firefox 152 reports its own limit
through maxActions. Read the getter to use the engine’s button limit.
Exceptions
Section titled “Exceptions”| Exception | When |
|---|---|
TypeError |
actions is non-empty on new Notification(). Chromium: Actions are only supported for persistent notifications shown using ServiceWorkerRegistration.showNotification(). |
TypeError |
An action object lacks action or title, which are required dictionary members. |
An unsupported option is not an exception: Firefox before 152 and Safari ignore actions, and
every engine except Chromium ignores badge, so the notification still displays, without the ignored feature.
Support position
Section titled “Support position”actions and badge shipped together in Chrome 53 (2016) and BCD lists both from Edge 18; Firefox added actions in 152 and still ignores badge; Safari supports neither on
macOS or iOS, where notification buttons are not part of the web notification surface (BCD
api.Notification.actions, api.Notification.badge). MDN says the platform uses the badge when there is not enough space for the full notification, for example in a status bar; which images appear depends on the browser and operating system.
Examples
Section titled “Examples”Call showNotification() from the page and handle the selected event.action in the service worker.
Two buttons with a handler per action
Section titled “Two buttons with a handler per action”The service worker reads event.action. The empty string means the body was tapped; anything
else is one of the action ids.
// pageawait registration.showNotification('New message from Ada', { body: 'Can we move the call to 3pm?', badge: '/icons/badge-96.png', tag: 'thread-42', data: { threadId: 42 }, actions: [ { action: 'reply', title: 'Reply' }, { action: 'mute', title: 'Mute thread' }, ],});
// service workerself.addEventListener('notificationclick', (event) => { event.notification.close(); const { threadId } = event.notification.data; if (event.action === 'mute') { event.waitUntil(fetch(`/api/threads/${threadId}/mute`, { method: 'POST' })); } else { event.waitUntil(self.clients.openWindow(`/threads/${threadId}${event.action === 'reply' ? '#compose' : ''}`)); }});Because the limit is two in Chromium, put the primary and the destructive action in that order; a third button would be dropped.
Sizing the badge image
Section titled “Sizing the badge image”The badge is drawn as a silhouette: every opaque pixel becomes white (or the system accent), so a logo with internal detail turns into a blob. Export a one-colour glyph with a transparent background at 96 by 96 pixels.
await registration.showNotification('Download complete', { body: 'report-2026-q3.pdf', icon: '/icons/icon-192.png', // full-colour, shown beside the text badge: '/icons/badge-96.png', // single colour, shown in the status bar});The icon and badge serve different slots and are both worth setting; a notification with only
icon shows the browser’s own glyph in the Android status bar.
Detecting the options and omitting them where unsupported
Section titled “Detecting the options and omitting them where unsupported”The options are properties of Notification.prototype where supported. Build the options object
conditionally so the same call works in Safari and Firefox.
function notificationOptions(base, buttons) { if (!('Notification' in window)) return null; // no notifications at all const options = { ...base }; if ('badge' in Notification.prototype) options.badge = '/icons/badge-96.png'; if ('actions' in Notification.prototype && Notification.maxActions > 0) { options.actions = buttons.slice(0, Notification.maxActions); } return options;}Slice to maxActions to keep the first buttons and control which later buttons are omitted.
This preserves the intended priority when the array order is “primary, secondary, destructive”.
See also
Section titled “See also”- Notifications API Standard: actions (whatwg.org)
- Notification: actions property (developer.mozilla.org)
- Notifications API
- Notification interface
- Badging API
Specifications
| Specification | Status |
|---|---|
| None. | |