The Notification API is a valuable tool for displaying system notifications to users. It provides a browser interface that allows developers to show messages to users, even if the website is not currently open in the browser.

Table of Contents

Introduction to the Notification API

The Notifications API enables developers to display native system notifications to users, even when the web app is not actively running. These notifications are familiar and consistent, as they adhere to the UI and UX standards of the operating system. When combined with the Push API, the Notification API can significantly enhance user engagement and expand the capabilities of your app.

Please note that the Notifications API interacts closely with Service Workers, as they are essential for Push Notifications. While it is possible to use the Notifications API without Push, its use cases may be limited.

if (window.Notification && Notification.permission !== "denied") {
 Notification.requestPermission((status) => {
 // status is "granted", if accepted by user
 var n = new Notification('Title', {
 body: 'I am the body text!',
 icon: '/path/to/icon.png' // optional
 })
 })
}

n.close()

Permissions

Before showing a notification to the user, it is necessary to obtain permission. This can be done by calling the Notification.requestPermission() method. By using the simple form Notification.requestPermission(), a permission granting panel will be displayed, unless the permission has already been granted.

To handle user interactions, such as allowing or denying the permission, you can attach a processing function to the request. Here is an example:

const process = (permission) => {
 if (permission === "granted") {
 // ok we can show the permission
 }
}

Notification.requestPermission((permission) => {
 process(permission)
}).then((permission) => {
 process(permission)
})

By passing a callback and using a promise, we can ensure compatibility with different implementations of Notification.requestPermission() across various browsers. The process() function receives a permission string which can have the values ‘granted’, ‘denied’, or ‘default’, depending on the user’s previous actions.

It is also possible to check the Notification.permission property, which evaluates to ‘granted’ or ‘denied’ if the user has already granted or denied permissions. If Notification.requestPermission() has not been called, the property will resolve to ‘default’.

Create a notification

The Notification object, available through the window object in the browser, allows you to create a notification and customize its appearance. Here is a simple example that creates a notification after obtaining permission:

Notification.requestPermission();
new Notification('Hey');

Create a notification

You can further customize the notification using the following options.

Add a body

You can include a body in the notification, which is typically displayed as a single line:

new Notification('Hey', {
 body: 'You should see this!'
});

Add a body to the notification

Add an image

You can also add an icon to the notification:

new Notification('Hey', {
 body: 'You should see this!',
 icon: '/user/themes/writesoftware/favicon.ico'
});

Add an image to the notification

For more customization options, including platform-specific properties, refer to the Mozilla Developer Network documentation.

Close a notification

If you need to close a notification that has been opened, you can store a reference to the notification and use it to close it later:

const n = new Notification('Hey');

To close the notification, simply call:

n.close();

Alternatively, you can use a timeout to automatically close the notification after a specified duration:

setTimeout(n.close(), 1000); // Close after 1 second