Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Browser and Web APIs

The Notifications API

Reference for the JavaScript Notifications API: Notification.permission, requestPermission(), constructor options, events, tags and service worker notifications.

The Notifications API shows system-level messages outside the page, in the operating system's notification area. A page asks the user for permission with Notification.requestPermission(), then creates new Notification(title, options) objects.

Permission has three states, available as Notification.permission: "default" (not asked yet), "granted" and "denied". Notifications work only in secure contexts, and most browsers require the permission request to be triggered by a user gesture. For notifications that must appear when the page is closed, use a service worker and its registration.showNotification() method together with the Push API.

JavaScript
if (Notification.permission === "granted") {
  new Notification("Build finished", { body: "All 42 tests passed." });
}

Try it

The sandboxed editors on this site cannot show system notifications, so the first example only reads the state and reports it, and the second runs the permission logic against a small stand-in object.

JS Checking support and permission

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS A notify() helper, tested with a stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
Notification.requestPermission()
const n = new Notification(title, options)
n.close()
Name Description
title Required string shown as the notification's heading.
options.body Secondary text.
options.icon URL of an icon image.
options.tag An ID string. A new notification with the same tag replaces the old one instead of stacking.
options.data Any value you want to read back later from n.data.
options.silent If true, suppresses sound and vibration.
options.requireInteraction Keeps the notification visible until the user acts, where supported.

Return value: requestPermission() returns a promise that fulfills with "granted", "denied" or "default". The Notification constructor returns the notification object.

Events on a notification: show, click, close and error. Set handlers with n.onclick = ... or addEventListener().

Usage notes

  • Ask in context. Request permission after the user does something that makes the value clear, such as turning on "Notify me when the export is ready". Asking on page load is often denied, and a "denied" answer usually cannot be changed from code.
  • Check before creating. Creating a notification without permission does nothing useful, so test Notification.permission first.
  • Use tag to avoid spam. Repeated updates with the same tag replace each other.
  • Handle clicks. In onclick, call window.focus() or n.close() so the notification does its job.
  • Mobile and PWAs. The new Notification() constructor may not be allowed on some mobile browsers. Use ServiceWorkerRegistration.showNotification() there.
  • Do not rely on them. Users can disable notifications at any level, so also show important messages inside the page.
  • Respect the user. Send only notifications the user would expect.

Browser support

The Notifications API is widely supported on desktop browsers. Support on mobile browsers, and for the constructor in particular, is more limited, so check a compatibility table.