JavaScript Notifications API: Complete Tutorial

The Notifications API lets your web app display system-level desktop notifications that appear outside the browser window. Unlike alert() which blocks the page and only shows inside the tab, notifications appear in the operating system's notification center and remain visible even when the browser is minimized.

Here is the smallest working notification you can send:

javascript

const notification = new Notification("New message received");

This creates a notification with the title "New message received". It appears briefly in the corner of the screen, then disappears. The user can see it even when they are in a different application.

Checking and requesting permission

Before sending notifications, you must check the current permission state. Browsers deny notifications by default, and the user must explicitly grant permission.

The permission state lives on Notification.permission and has three possible values. The string "granted" means the user allowed notifications and you can send them freely. The string "denied" means the user blocked them and you cannot ask again. The string "default" means the user has not decided yet and you need to request permission.

javascript

if (Notification.permission === "granted") {
  new Notification("You have already granted permission");
} else if (Notification.permission !== "denied") {
  Notification.requestPermission().then((permission) => {
    if (permission === "granted") {
      new Notification("Thanks for allowing notifications");
    }
  });
}

The requestPermission method must be called from a user gesture like a button click. Calling it on page load is blocked by modern browsers. For a complete walkthrough of the permission flow, see the companion article on notification permissions.

Adding body, icon, and tag

The Notification constructor accepts an options object as its second argument. These properties customize how the notification looks and behaves:

javascript

const notification = new Notification("Build complete", {
  body: "The project compiled successfully with no errors.",
  icon: "/icons/build-success.png",
  tag: "build-status",
});

The body property adds descriptive text below the title. The icon property sets a small image shown next to the title. The tag property groups related notifications, so sending a second notification with the same tag replaces the first one instead of stacking.

Handling notification clicks

When the user clicks a notification, you can respond by listening for the click event. A common pattern is to focus the browser window or navigate to a specific page:

javascript

const notification = new Notification("New comment", {
  body: "Rune replied to your post",
  tag: "comment-reply",
});
 
notification.addEventListener("click", () => {
  window.focus();
  console.log("User clicked the notification");
});

The click handler fires when the user interacts with the notification. Calling window.focus brings the browser tab to the foreground, which is what most users expect after clicking a notification.

Closing notifications programmatically

Notifications auto-dismiss after a few seconds on most platforms, but you can also close them from code:

javascript

const notification = new Notification("Processing");
setTimeout(() => {
  notification.close();
}, 3000);

The close method removes the notification from the screen. Combined with the close event, you can track when a notification disappears whether by user action or timeout.

Common mistakes

• Calling requestPermission on page load instead of on a user gesture. Modern browsers silently ignore it.
• Not checking Notification.permission before creating a notification. Calling the constructor with "denied" permission does nothing or throws.
• Forgetting that notifications need a secure context. The API requires HTTPS or localhost.
• Expecting notification actions and images to work consistently across all browsers and operating systems.
• Using notifications for critical information. Users may have notifications disabled system-wide.

Related articles

• Requesting Desktop Notification Permissions in JS -- the full permission flow in detail
• How to Add Event Listeners in JS: Complete Guide -- event handling patterns that apply to notification clicks

Quick reference