Skip to content

API in Notifications

Notifications API

Published Updated

The Notifications API displays messages through the operating system’s own notification surface, outside the page, so they remain visible after the user switches tabs or apps. A persistent notification created by ServiceWorkerRegistration.showNotification() outlives the page. MDN notes that the Notification() constructor throws a TypeError on most mobile browsers, so code that must run on mobile devices has to use persistent notifications. A page can also create a non-persistent notification with new Notification(); see the constructor reference.

registration.showNotification(title)
registration.showNotification(title, options)
registration.getNotifications()
registration.getNotifications({ tag })

showNotification() returns a Promise<void> that fulfils once the notification is handed to the OS; getNotifications() resolves with the Notification objects this registration has shown, in creation order, optionally filtered by tag. Both are available in windows and in the service worker itself (self.registration), and require a secure context (BCD api.ServiceWorkerRegistration.showNotification: Chrome 42, Firefox 44, Safari 16 on macOS Ventura, Safari 16.4 on iOS for Home Screen web apps).

Parameter Type Meaning
title string The first line of the notification. Required.
options.body string Secondary text under the title.
options.icon string (URL) Large image beside the text.
options.badge string (URL) Small monochrome image used where the full notification does not fit, such as the Android status bar. Chromium only; see actions and badge.
options.image string (URL) Large picture below the text. Chromium only.
options.tag string Identifier; a new notification with the same tag replaces the old one.
options.renotify boolean Alert the user again when replacing by tag. Requires a non-empty tag. Chromium only.
options.requireInteraction boolean Keep the notification on screen until the user acts. Chromium; Firefox 117 on Windows only.
options.silent boolean Suppress sound and vibration. Chrome 43, Firefox 132, Safari 16.6. Incompatible with vibrate.
options.data any structured-cloneable value Payload read back as event.notification.data in notificationclick.
options.actions array Buttons; persistent notifications only. See the actions entry.
options.navigate string (URL) Safari 18.4: open this URL on activation instead of firing notificationclick.
options.timestamp, options.vibrate, options.dir, options.lang number, array, string, string Display time, vibration pattern (Chromium on Android), text direction, BCP 47 language tag.

A persistent notification has a non-null service worker registration. Its notificationclick and notificationclose events fire on the ServiceWorkerGlobalScope, it should appear in the platform’s notification centre, and it may carry actions. A non-persistent one fires click and close on its Notification object, should be closed by the browser a couple of seconds after creation (the standard says user agents should), and its constructor throws on a non-empty actions array.

Exception When
TypeError The registration has no worker in the activating or activated state. navigator.serviceWorker.ready resolves only when one exists, which is why examples await it.
TypeError Notification.permission is not "granted". Chromium’s message is Failed to execute 'showNotification' on 'ServiceWorkerRegistration': No notification permission has been granted for this origin. (service_worker_registration_notifications.cc, chromium.googlesource.com).
TypeError renotify is true with an empty tag, or silent is true together with vibrate.
DataCloneError DOMException options.data cannot be structured-cloned (a function, a DOM node).

The promise rejects; nothing is thrown synchronously. A rejected showNotification() inside a push handler also breaks the userVisibleOnly promise, which WebKit answers by revoking the subscription, so check these conditions before calling it rather than in a catch.

Desktop support is complete: Chrome 42, Edge 17, Firefox 44, and Safari 16 on macOS Ventura. Mobile is where the shape matters. Chrome for Android (42) and Samsung Internet expose notifications only through a service worker and make the constructor throw; Safari on iOS and iPadOS 16.4 exposes the interface only inside a Home Screen web app, and only through a service worker; Android WebView has no implementation (BCD api.Notification). Chrome also disables notifications in Incognito windows from version 49. Use persistent notifications to support both desktop and mobile browsers.

Show notifications from the page and handle their clicks in the service worker.

Showing a persistent notification from the page

Section titled “Showing a persistent notification from the page”

Wait for an active worker, then call showNotification() on the registration. The data member carries what the click handler needs.

async function notify(title, body, url) {
const registration = await navigator.serviceWorker.ready;
await registration.showNotification(title, {
body,
icon: '/icons/icon-192.png',
tag: 'inbox',
data: { url },
});
}

tag: 'inbox' collapses repeated calls into one notification, which is what the user wants for “3 new messages” and not what they want for three separate chat threads.

Persistent notifications fire notificationclick on the worker. Close the notification, then focus an existing window if one is open at the target URL and open a new one otherwise.

self.addEventListener('notificationclick', (event) => {
event.notification.close();
const url = new URL(event.notification.data?.url ?? '/', self.location.origin).href;
event.waitUntil((async () => {
const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
const open = windows.find((client) => client.url === url);
if (open) return open.focus();
return self.clients.openWindow(url);
})());
});

event.action is the empty string when the body was clicked and the action id when a button was; the handler above treats both the same.

Detecting a usable notifier and falling back

Section titled “Detecting a usable notifier and falling back”

Check that the interface exists, permission is granted, and the registration has an active worker. Return an in-page fallback if any check fails. Awaiting ready on a page with no registration would leave the call pending.

async function getNotifier() {
if (!('Notification' in window) || !('serviceWorker' in navigator)) {
return showInPageBanner; // iOS tab or embedded web view: no system notifications
}
const registration = await navigator.serviceWorker.getRegistration();
if (!registration?.active || Notification.permission !== 'granted') {
return showInPageBanner; // not yet installed, or permission not granted
}
return (title, body) => registration.showNotification(title, { body });
}

The returned function has the same signature in both branches, so callers do not care which one they got.

Specifications

SpecificationStatus
None.