Notifications API

Concepts and usage

Requesting permission

A website can only display notifications if the user has granted it permission to do so. To ask permission, the website needs to call the static Notification.requestPermission() method. This method should only be called when handling a user gesture, such as when handling a mouse click. For example:

button.addEventListener("click", async () => {
  const permission = await Notification.requestPermission();
  if (permission === "granted") {
    // we can show the notification
  } else {
    // we can't show the notification
  }
});

The requestPermission() method returns a Promise which resolves to one of the following three string values:

• "granted": the user granted permission.
• "denied": the user denied permission.
• "default": the user has neither granted nor denied permission.

When the site calls requestPermission(), if the user has not already granted or denied permission for this origin, then the browser shows the user a dialog asking them if they want to grant or deny permission:

Once the user has made a choice, the browser will resolve the returned promise with their choice, and remember it.

If the user has already chosen to grant or deny notifications for this origin, then requestPermission() will immediately resolve the promise with their choice.

Persistent and non-persistent notifications

The specification distinguishes two sorts of notifications, persistent notifications and non-persistent notifications. These serve different use cases and involve different APIs.

Persistent notifications

Persistent notifications are created in a web page or a service worker, by calling ServiceWorkerRegistration.showNotification(), and any user interaction with the notification is always handled in the service worker.

The browser should display the notification in the platform's notification center, if that is available, and the notification may persist in the notification center until it is removed (for example, because the user closed it).

When a persistent notification is created, you can pass it an array of action objects: these are typically things the user might want the website to do in response to the notification. For example, an email app might display a notification which gives the user the chance to delete the email or open it.

const registration = await navigator.serviceWorker.ready;
registration.showNotification("You have a new email", {
  actions: [
    { action: "open", title: "Open this email" },
    { action: "delete", title: "Delete this email" },
  ],
});

The actions will be presented to the user in the notification, for example as buttons they can press or options they can select.

When the user clicks a persistent notification, the notificationclick event is fired in the service worker's global scope. If the user selected an action, it is given as the action property of the event passed into the notificationclick handler, and the service worker can use it to decide what to do:

self.addEventListener("notificationclick", (event) => {
  switch (event.action) {
    case "open":
      clients.openWindow("actions/open.html");
      break;
    case "delete":
      clients.openWindow("actions/delete.html");
      break;
  }
});

Non-persistent notifications

Non-persistent notifications are always created in a web page, by calling the Notification() constructor, and user interaction with the notification is always handled in the web page.

The browser should not display the notification in the platform's notification center, and should automatically close the notification after a few seconds.

The web page can handle user interactions with the notification by listening for the click and close events.

const notification = new Notification("Hello!");

notification.addEventListener("click", () => {
  console.log("clicked!");
});

notification.addEventListener("close", () => {
  console.log("closed!");
});

These events are passed a generic Event object — unlike a persistent notification, with a non-persistent notification you can't provide actions, and therefore can't be informed about which action the user chose.

Which type should you use?

The most common use case for a notification is when something happens in your web app that the user should know about, but they should not be forced to immediately stop whatever else they are doing. For example, your web app is an email app and you have received a new email. You might want the user to know that they have an email, and when they are ready to deal with it, you want to handle their response — for example, to read the email or delete it unread.

To meet this use case you need to use persistent notifications, because web pages are inherently ephemeral. The user could close the page at any time, and if they do so, the notification object is destroyed along with any event listeners, so your web app will not able to handle the user's response.

However, if your notification is managed by a service worker, then when the user interacts with the notification, the browser will automatically resume your service worker and fire its notificationclick event.

On mobile devices, the situation for non-persistent notifications is even more challenging, because a mobile browser might stop a page from running as soon as it is put in the background. For this reason, Chromium-based browsers don't support non-persistent notifications at all on mobile, and the Notification() constructor will throw an exception.

Interfaces

Notification

Defines a notification object.

NotificationEvent

Represents a notification event dispatched on the ServiceWorkerGlobalScope of a ServiceWorker.

Extensions to other interfaces

notificationclick event

Occurs when a user clicks on a persistent notification.

notificationclose event

Occurs when a user closes a persistent notification.

ServiceWorkerRegistration.getNotifications()

Returns a list of persistent notifications in the order that they were created from the current origin via the current service worker registration.

ServiceWorkerRegistration.showNotification()

Displays the persistent notification with the requested title.

Specifications

Browser compatibility

api.Notification

api.ServiceWorkerRegistration.showNotification

api.ServiceWorkerRegistration.getNotifications

See also

• Using the Notifications API