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.
Syntax
Section titled “Syntax”new Notification(title)new Notification(title, options)notification.close()Notification.permissionNotification.maxActionsThe 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.
Members
Section titled “Members”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.
Exceptions
Section titled “Exceptions”| 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.
Platform availability
Section titled “Platform availability”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.
Examples
Section titled “Examples”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.
See also
Section titled “See also”- Notifications API Standard: Notification interface (whatwg.org)
- Notification: Notification() constructor (developer.mozilla.org)
- Notifications API
- Notification.requestPermission()
- Notification actions and badge options
Specifications
| Specification | Status |
|---|---|
| None. | |