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.
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.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
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.permissionfirst. - Use
tagto avoid spam. Repeated updates with the same tag replace each other. - Handle clicks. In
onclick, callwindow.focus()orn.close()so the notification does its job. - Mobile and PWAs. The
new Notification()constructor may not be allowed on some mobile browsers. UseServiceWorkerRegistration.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.