Skip to content

API in Notifications

Notification interface

Published

Notification represents a displayed notification and exposes its properties and events. new Notification(title, options) creates and immediately shows a non-persistent notification from a page or dedicated worker, and the same interface is handed to a service worker as event.notification for persistent ones. Its instance properties mirror the options it was created with, and its events report display, activation, dismissal, and failure.

new Notification(title)
new Notification(title, options)
notification.close()
Notification.permission
Notification.maxActions

The constructor is exposed on Window and in dedicated and shared workers, and throws in a ServiceWorkerGlobalScope, where self.registration.showNotification() is the replacement. Desktop support is Chrome 20, Firefox 22, Safari 7, Edge 14 (BCD api.Notification.Notification). On mobile, BCD records that the constructor always throws in Chrome for Android and Samsung Internet, and that it is exposed in Safari on iOS only in Home Screen web apps, which still send notifications through ServiceWorkerRegistration.showNotification() (details under Exceptions). MDN warns that it throws in nearly all mobile browsers.

Instance members are read-only and reflect the constructor’s options.

Member Type Meaning
title, body, icon, image, badge string The texts and image URLs passed at creation. Missing options read as "".
tag string Replacement key. A later notification with the same tag from the same origin replaces this one.
data any The structured-cloneable payload passed as options.data; null when none.
dir, lang string Text direction ("auto", "ltr", "rtl") and BCP 47 language tag.
requireInteraction, renotify, silent boolean (silent may be null) Behaviour flags; see the Notifications API parameter table for engine support.
timestamp number The time the notification is about, in milliseconds since the epoch; defaults to creation time.
vibrate array of numbers Vibration pattern, Chromium on Android.
actions array Empty on a notification created with the constructor, which throws if options.actions is non-empty; may be populated on event.notification in a service worker.
navigate string URL opened on activation, Safari 18.4.

Events are show (displayed; not fired by Safari on iOS), click, close, and error (display failed, for example because permission was revoked between the check and the call). The static Notification.permission is covered in Notification.requestPermission(); Notification.maxActions returns the number of action buttons the engine will display, 2 in Chromium (kMaximumActions in notification.mojom, chromium.googlesource.com) and undefined in Safari, where the static is absent.

Exception When
TypeError The constructor is called in a service worker. Chromium’s message is Illegal constructor. when the NotificationConstructor feature is enabled (notification.cc, chromium.googlesource.com).
TypeError The constructor is called in Chrome for Android or Samsung Internet, from any context; BCD records that the constructor always throws there (api.Notification.Notification, chrome_android). Chromium’s message there is Illegal constructor. Use ServiceWorkerRegistration.showNotification() instead.
TypeError options.actions is non-empty. Chromium’s message is Actions are only supported for persistent notifications shown using ServiceWorkerRegistration.showNotification().
TypeError renotify is true with an empty tag, or silent is true with vibrate set.
ReferenceError Safari on iOS and iPadOS in a browser tab: the Notification identifier does not exist unless the page is a Home Screen web app with a non-default manifest display.

A denied or undecided permission is not an exception. The constructor returns a Notification whose error event fires and nothing is displayed, which is why Notification.permission is checked before the call.

The interface is available in the desktop browsers listed above. On mobile it varies: Chrome for Android 42 and Samsung Internet 4 expose it for service worker use only, Safari on iOS 16.4 exposes it only inside Home Screen web apps, and Android WebView has none (BCD api.Notification). Chrome from version 49 does not show notifications in Incognito. Support for instance members and events varies by member in BCD. For example, show is missing on iOS, and Safari does not support actions, badge, image, renotify, timestamp, or vibrate.

The constructor example is written for desktop. Reading a persistent notification and falling back from the constructor also work on Android and iOS.

Showing a non-persistent notification on desktop

Section titled “Showing a non-persistent notification on desktop”

With permission already granted, the constructor displays immediately. The click handler focuses the window and closes the notification; without close() the OS keeps it until its own timeout.

function showOrderUpdate(orderId) {
const notification = new Notification('Order shipped', {
body: `Order #${orderId} is on its way.`,
icon: '/icons/parcel.png',
tag: `order-${orderId}`,
data: { orderId },
});
notification.addEventListener('click', () => {
window.focus();
location.hash = `#order-${notification.data.orderId}`;
notification.close();
});
notification.addEventListener('error', () => console.warn('Notification not shown'));
}

The standard says browsers should close a non-persistent notification on their own a couple of seconds after creation and keep it out of the notification centre, so use it for “saved” confirmations. It does not suit messages the user needs to return to.

Reading a persistent notification in the service worker

Section titled “Reading a persistent notification in the service worker”

In a notificationclick handler the same interface arrives as event.notification, with close() available. Its actions array is empty unless the notification was created with buttons.

self.addEventListener('notificationclick', (event) => {
const { tag, data, actions } = event.notification;
event.notification.close();
if (event.action === 'archive') {
event.waitUntil(fetch(`/api/threads/${data.threadId}/archive`, { method: 'POST' }));
return;
}
event.waitUntil(self.clients.openWindow(`/inbox#${tag}`));
});

Where actions and Notification.maxActions are supported, the specification skips entries beyond the maxActions limit when the notification is created, so they are absent from its actions array.

Detecting whether the constructor is usable

Section titled “Detecting whether the constructor is usable”

The reliable probe is to construct inside try after confirming the interface and permission. Any failure routes to the persistent path, which is also the only path on Android and iOS.

async function show(title, options) {
if (!('Notification' in window) || Notification.permission !== 'granted') {
return showInPage(title, options.body); // no interface, or no permission
}
try {
return new Notification(title, options);
} catch (err) {
if (err.name !== 'TypeError') throw err;
const registration = await navigator.serviceWorker.getRegistration();
if (!registration?.active) return showInPage(title, options.body); // nothing to fall back to
return registration.showNotification(title, options);
}
}

MDN recommends showNotification() when a service worker is active and the constructor otherwise.

Specifications

SpecificationStatus
None.