Notifications API

Notifications API is the browser interface that lets a web page show a system notification outside the page, after the user has granted permission for the site's origin. It is defined by the WHATWG Notifications Standard. The permission state is one of three strings: default, granted or denied, and only granted lets a notification appear.

How it works

The Notification class works with two static members. Notification.permission reads the current state, and Notification.requestPermission() asks the user and returns a Promise that resolves to the new state. The older callback form is deprecated. Creating new Notification("Title", { body: "Text" }) shows a notification when the state is granted. If it is not granted, the object fires an error event.

• Permission default means the user has not decided. The browser treats it like denied, and no notification appears.
• Browsers do not normally show the prompt again after the user chooses denied. The user has to change the setting in the browser.
• Options include body, icon, image, badge, tag, lang, dir, silent and data. A new notification with the same tag as an existing one replaces it instead of stacking.
• Events on the object are click, show, error and close.
• The specification recommends the Permissions API query for notifications over reading permission synchronously.

There are two kinds. A non-persistent notification is created with the constructor from a page. A persistent notification is created by calling showNotification on a service worker registration, survives the page closing, and is the only kind that supports action buttons. Many mobile browsers throw a TypeError for the constructor, so the service worker route is the portable choice.

function notificationState() {
  if (!('Notification' in globalThis)) return 'unsupported';
  return Notification.permission;
}
console.log(typeof Notification, notificationState());

Run in Node.js 22.22.0, which has no Notification class, this prints the unsupported branch. In a browser it prints function and then default, granted or denied.

undefined unsupported

How do you ask for notification permission?

Call Notification.requestPermission() from a click handler and await the result. Browsers ignore or block requests that do not follow a user gesture, and Firefox has required one since version 72. Chrome and Firefox also require a secure context, and they block requests from cross-origin iframes. Ask after the user shows interest, such as pressing an "Enable alerts" button, not on page load.

Why are my notifications not showing?

The usual reasons are that permission is not granted, the page is not on HTTPS, or the operating system has notifications turned off for the browser. Check Notification.permission first. If it reads denied, the user has to change the setting in the browser. Operating system settings can also hide notifications without any error in the page.

Common pitfalls

• Requesting permission on load: users often deny, and browsers do not normally prompt a denied origin again. Wait for a user action and explain the benefit first.
• Using the constructor on mobile: it can throw a TypeError. Register a service worker and call registration.showNotification instead.
• Assuming a granted state is permanent: users can revoke it in browser settings at any time, so check permission before each send.
• Treating notifications as web push: this API only displays something. Delivering a message while the site is closed needs the Push API on top of a service worker.
• Missing tag: repeating events create a pile of notifications. Set tag to replace the earlier one.
• Untrusted text in body: body is plain text, but it still appears outside your site, so avoid showing secrets on a locked screen.

Related terms

• Service worker — the background script that shows persistent notifications
• PWA — installable web apps that commonly use notifications
• HTTPS — the secure transport the API requires
• Promise — what requestPermission returns
• Async/await — the syntax for waiting on the permission result
• DOM — the page environment where the Notification constructor runs

See also

• Term: Service worker — explains the registration that persistent notifications depend on