files/en-us/web/api/notifications_api/index.md
{{DefaultAPISidebar("Web Notifications")}}{{securecontext_header}} {{AvailableInWorkers}}
The Notifications API allows web pages to control the display of system notifications to the end user. These are outside the top-level browsing context viewport, so therefore can be displayed even when the user has switched tabs or moved to a different app. The API is designed to be compatible with existing notification systems, across different platforms.
Showing a system notification generally involves first requesting permission to use the feature, and then creating a notification.
In order to use notifications, the user needs to grant the current origin permission to display system notifications. This is generally done when the app or site initializes, using the {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}} method. This method should only be called when handling a user gesture, such as when handling a mouse click. For example:
btn.addEventListener("click", () => {
let promise = Notification.requestPermission();
// wait for permission
});
This will spawn a request dialog, along the following lines:
From here the user can choose to allow notifications from this origin, or block them. Once a choice has been made, the setting will generally persist for the current session.
Notifications are created using the {{domxref("Notification.Notification","Notification()")}} constructor. This must be passed a title argument, and can optionally be passed a parameter to specify options such as text direction, body text, icon to display, notification sound to play, and more.
For example, the following code shows how you might create a notification that sets the navigate option, specifying a URL that will be opened if the notification is accepted (you can also defined click handlers to process notification actions).
if (Notification.permission === "granted") {
const notification = new Notification("New message from Alice", {
body: "Hey, are you free for lunch?",
navigate: "/messages/alice",
});
}
For more usage examples see Using the Notifications API.
The Notifications API supports two types of notifications:
Non-persistent notifications are created in a browsing context, such as a web page or tab. Their lifetime is tied to the lifetime of the page — if the page is closed, the notification can no longer be interacted with.
They are created using the {{domxref("Notification.Notification","Notification()")}} constructor and fire events such as {{domxref("Notification/click_event", "click")}} directly on the Notification instance
Persistent notifications are created from a service worker, and can remain interactive beyond the lifetime of an individual page.
They are created using {{domxref("ServiceWorkerRegistration.showNotification()")}} from a service worker and fire {{domxref("ServiceWorkerGlobalScope/notificationclick_event", "notificationclick")}} and {{domxref("ServiceWorkerGlobalScope/notificationclose_event", "notificationclose")}} events on the {{domxref("ServiceWorkerGlobalScope")}}.
{{Specifications}}
{{Compat}}