The Notification API allows web pages to show notifications. This API can show notifications only if the user grants permission to receive notifications and the current web page is serving from an HTTPS protocol.

Checking notification permission

The permission property of the Notification object returns the current notification permission. It can have three possible values:

• granted – user has given permission to show the notification.
• denied – user has denied permission to show the notification.
• default – user choice is unknown and the browser will consider it denied.

To ask the user for notification permission, we use the requestPermission() method of the Notification object. This method returns a Promise that resolves with the opted permission value, i.e., granted or denied.

const permission = await Notification.requestPermission();
console.log(permission); // granted or denied

Send notification

We can use the Notification() constructor to create a new notification. It takes the title of the notification and an optional configuration object as arguments.

new Notification("New message");

We can use the configuration object to customize the notification. Let’s discuss some of the most used options.

• body – the body text of the notification that appears below the title.
• icon – the icon of the notification.
• tag – a unique string ID of the notification. Notifications with similar IDs replace each other, i.e., when a new notification comes, the older one closes.
• image* – an image to show in the notification.
• vibrate* – a vibration pattern as specified in the Vibration API to vibrate the device (if vibration hardware exists) when the notification is displayed.

All * marked options have very less number of browser support. Check the browser compatibility here before using.

new Notification("New message", {
  tag: "MESSAGE123",
  body: "You have got a new message",
  icon: "logo.png",
  image: "image.jpg",
  vibrate: 500,
});

To programmatically close the notification, we can call the close() method on the notification instance.

const notification = new Notification("New message", {
  body: "You have got a new message",
  icon: "logo.png",
});

// call close() where you require
notification.close();

Notification events

The Notification API provides the following events that we can listen to and run some code.

• click – It fires when the user clicks on the notification.
• close – It fires when the user closes the notification.
• show – It fires when the notification is displayed.
• error – It fires when some error occurs.

Let’s see one example to log all the events and open a web page when the user clicks on the notification.

const notification = new Notification("New message", {
  body: "You have got a new message",
  icon: "logo.png",
});

notification.addEventListener("click", () => {
  console.log("User opened the notification");
  notification.close(); // close notification when user clicks on it
  window.open("http://jscurious.com", "_blank");
});

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

notification.addEventListener("show", () => {
  console.log("Notification displayed");
});

notification.addEventListener("error", (e) => {
  console.log("Some error occured", e);
});

Notification sound

The Notification API doesn’t provide any support to play a sound when the notification is displayed. Therefore we have to manually play a sound when we trigger a notification. We will make use of the HTMLAudioElement API to play the notification sound.

const sound = new Audio("sound.mp3");
const notification = new Notification("New message", {
  body: "You have got a new message",
  icon: "logo.png",
});

notification.addEventListener("show", () => {
  sound.play();
  console.log("Notification displayed");
});

Let’s see one live example below to create a notification. Make sure to allow the notification permission to run this example. If you don’t see a prompt asking for notification permission, then you can click on the lock icon in the search bar present before the domain URL and provide permission from there.

You may also like

• Play audio with HTMLAudioElement API in JavaScript
• The URLSearchParams API in JavaScript
• JavaScript Fetch API to make HTTP requests
• The Vibration API in JavaScript

Amitav Mishra

Web Developer by Profession, Blogger by Passion.
JavaScript | React | Next |  Angular | Vue | HTML | CSS