Note: This feature is available in Web Workers.

Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The Notifications API lets a web page or app send notifications that are displayed outside the page at the system level; this lets web apps send information to a user even if the application is idle or in the background. This article looks at the basics of using this API in your own apps.

Typically, system notifications refer to the operating system's standard notification mechanism: think for example of how a typical desktop system or mobile device broadcasts notifications.

The system notification system will vary of course by platform and browser, but this is ok, and the Notifications API is written to be general enough for compatibility with most system notification systems.

Examples

One of the most obvious use cases for web notifications is a web-based mail or IRC application that needs to notify the user when a new message is received, even if the user is doing something else with another application. Many real examples of this now exist, such as Slack.

We've written a real world example—a to-do list app—to give more of an idea of how web notifications can be used. It stores data locally using IndexedDB and notifies users when tasks are due using system notifications. Download the To-do list code, or view the app running live.

Requesting permission

Before an app can send a notification, the user must grant the application the right to do so. This is a common requirement when an API tries to interact with something outside a web page — at least once, the user needs to specifically grant that application permission to present notifications, thereby letting the user control which apps/sites are allowed to display notifications.

Because of abuses of push notifications in the past, web browser developers have begun to implement strategies to help mitigate this problem. For example, Safari 12.1 now requires that the user interact with the page in some way before the page can request permission to perform push notifications. This at least prevents the user from getting spontaneously asked this question on web pages thaty've only glanced at once may rarely if ever look at again.

Checking current permission status

You can check to see if you already have permission by checking the value of the Notification.permission read only property. It can have one of three possible values:

default
The user hasn't been asked for permission yet, so notifications won't be displayed.
granted
The user has granted permission to display notifications, after having been asked previously.
denied
The user has explicitly declined permission to show notifications.

Getting permission

If permission to display notifications hasn't been granted yet, the application needs to use the Notification.requestPermission() method to request this from the user. In its simplest form, we just include the following:

Notification.requestPermission().then(function(result) {
  console.log(result);
});

This uses the promise-based version of the method. If you want to support older versions, you might have to use the older callback version, which looks like this:

Notification.requestPermission();

The callback version optionally accepts a callback function that is called once the user has responded to the request to display permissions (as seen in the second else ... if block below.) Commonly, you'll ask for permission to display notifications when your app is first initialized, and before trying to instantiate any. If you wanted to be really thorough, you could use a construct like the following (see To-do List Notifications):

function notifyMe() {
  // Let's check if the browser supports notifications
  if (!("Notification" in window)) {
    alert("This browser does not support system notifications");
    // This is not how you would really do things if they aren't supported. :)
  }

  // Let's check whether notification permissions have already been granted
  else if (Notification.permission === "granted") {
    // If it's okay let's create a notification
    var notification = new Notification("Hi there!");
  }

  // Otherwise, we need to ask the user for permission
  else if (Notification.permission !== 'denied') {
    Notification.requestPermission(function (permission) {
      // If the user accepts, let's create a notification
      if (permission === "granted") {
        var notification = new Notification("Hi there!");
      }
    });
  }

  // Finally, if the user has denied notifications and you 
  // want to be respectful there is no need to bother them any more.
}

Note: Before version 37, Chrome doesn't let you call Notification.requestPermission() in the load event handler (see issue 274284).

In Chrome 62+ and Firefox 67+ you cannot request notifications at all unless the site is a secure context (i.e. HTTPS).

Creating a notification

Creating a notification is easy; just use the Notification constructor. This constructor expects a title to display within the notification and some options to enhance the notification such as an icon or a text body.

For example, in the to-do-list example we use the following snippet to create a notification when required (found inside the createNotification() function):

var img = '/to-do-notifications/img/icon-128.png';
var text = 'HEY! Your task "' + title + '" is now overdue.';
var notification = new Notification('To do list', { body: text, icon: img });

Closing notifications

Firefox and Safari close notifications automatically after a few moments (around four seconds). This may also happen at the operating system level. Some browsers don't however, such as Chrome. To make sure that the notifications close in all browsers, you can call the Notification.close function inside a setTimeout() function to close the notification after 4 seconds. Also note the use of bind() to make sure the close() call is associated with the notification.

setTimeout(notification.close.bind(notification), 4000);

Note: When you receive a "close" event, there is no guarantee that it's the user who closed the notification. This is in line with the specification, which states: "When a notification is closed, either by the underlying notifications platform or by the user, the close steps for it must be run."

Notification events

There are four events that are triggered on the Notification instance:

click
Triggered when the user clicks on the notification.
close
Triggered once the notification is closed.
error
Triggered if something goes wrong with the notification; this is usually because the notification couldn't be displayed for some reason.
show
Triggered when the notification is displayed to the user.

These events can be tracked using the onclickoncloseonerror, and onshow handlers. Because Notification also inherits from EventTarget, it's possible to use the addEventListener() method on it.

Replacing existing notifications

It is usually undesirable for a user to receive a lot of notifications in a short space of time — for example, what if a messenger application notified a user for each incoming message, and they were being sent a lot? To avoid spamming the user with too many notifications, it's possible to modify the pending notifications queue, replacing single or multiple pending notifications with a new one.

To do this, it's possible to add a tag to any new notification. If a notification already has the same tag and has not been displayed yet, the new notification replaces that previous notification. If the notification with the same tag has already been displayed, the previous notification is closed and the new one is displayed.

Tag example

Assume the following basic HTML:

<button>Notify me!</button>

It's possible to handle multiple notifications this way:

window.addEventListener('load', function () {
  // At first, let's check if we have permission for notification
  // If not, let's ask for it
  if (window.Notification && Notification.permission !== "granted") {
    Notification.requestPermission(function (status) {
      if (Notification.permission !== status) {
        Notification.permission = status;
      }
    });
  }

  var button = document.getElementsByTagName('button')[0];

  button.addEventListener('click', function () {
    // If the user agreed to get notified
    // Let's try to send ten notifications
    if (window.Notification && Notification.permission === "granted") {
      var i = 0;
      // Using an interval cause some browsers (including Firefox) are blocking notifications if there are too much in a certain time.
      var interval = window.setInterval(function () {
        // Thanks to the tag, we should only see the "Hi! 9" notification 
        var n = new Notification("Hi! " + i, {tag: 'soManyNotification'});
        if (i++ == 9) {
          window.clearInterval(interval);
        }
      }, 200);
    }

    // If the user hasn't told if he wants to be notified or not
    // Note: because of Chrome, we are not sure the permission property
    // is set, therefore it's unsafe to check for the "default" value.
    else if (window.Notification && Notification.permission !== "denied") {
      Notification.requestPermission(function (status) {
        // If the user said okay
        if (status === "granted") {
          var i = 0;
          // Using an interval cause some browsers (including Firefox) are blocking notifications if there are too much in a certain time.
          var interval = window.setInterval(function () {
            // Thanks to the tag, we should only see the "Hi! 9" notification 
            var n = new Notification("Hi! " + i, {tag: 'soManyNotification'});
            if (i++ == 9) {
              window.clearInterval(interval);
            }
          }, 200);
        }

        // Otherwise, we can fallback to a regular modal alert
        else {
          alert("Hi!");
        }
      });
    }

    // If the user refuses to get notified
    else {
      // We can fallback to a regular modal alert
      alert("Hi!");
    }
  });
});

See the live result below:

Specifications

Specification Status Comment
Notifications API Living Standard Living standard

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
NotificationChrome Full support 22
Notes
Full support 22
Notes
Notes Before Chrome 22, the support for notification followed an old prefixed version of the specification and used the navigator.webkitNotifications object to instantiate a new notification. Before Chrome 32, Notification.permission was not supported. Before Chrome 42, service worker additions were not supported. Starting in Chrome 49, notifications do not work in incognito mode.
Full support 5
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support 14Firefox Full support 22
Full support 22
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: moz
IE No support NoOpera Full support 25Safari Full support 6WebView Android No support NoChrome Android Full support YesFirefox Android Full support 22
Full support 22
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Opera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
Available in workersChrome Full support 45Edge Full support YesFirefox Full support 41IE No support NoOpera Full support 32Safari ? WebView Android No support NoChrome Android Full support 45Firefox Android Full support 41Opera Android Full support 32Safari iOS No support NoSamsung Internet Android ?
Secure context requiredChrome Full support 62Edge ? Firefox Full support 67IE No support NoOpera Full support 49Safari ? WebView Android No support NoChrome Android Full support 62Firefox Android Full support 67Opera Android Full support 46Safari iOS No support NoSamsung Internet Android ?
Notification() constructorChrome Full support 22
Full support 22
Full support 5
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support YesFirefox Full support 22
Full support 22
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: moz
IE No support NoOpera Full support 25Safari Full support 6WebView Android No support NoChrome Android Full support YesFirefox Android Full support 22
Full support 22
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: moz
Opera Android Full support YesSafari iOS No support NoSamsung Internet Android ?
actionsChrome Full support 53Edge Full support 18Firefox No support NoIE No support NoOpera Full support 39Safari ? WebView Android No support NoChrome Android Full support 53Firefox Android No support NoOpera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support Yes
badgeChrome Full support 53Edge Full support 18Firefox No support NoIE No support NoOpera Full support 39Safari ? WebView Android No support NoChrome Android Full support 53Firefox Android No support NoOpera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support Yes
bodyChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
dataChrome Full support YesEdge Full support 16Firefox Full support YesIE No support NoOpera Full support YesSafari ? WebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
dirChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
iconChrome Full support 22
Full support 22
Full support 5
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support 14Firefox Full support 22
Full support 22
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: moz
IE No support NoOpera Full support 25Safari No support NoWebView Android No support NoChrome Android Full support YesFirefox Android Full support 22
Full support 22
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: moz
Opera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
imageChrome Full support 53Edge Full support 18Firefox No support NoIE No support NoOpera Full support 40Safari ? WebView Android No support NoChrome Android Full support 53Firefox Android No support NoOpera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support Yes
langChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
maxActionsChrome Full support YesEdge Full support 18Firefox No support NoIE No support NoOpera Full support YesSafari ? WebView Android No support NoChrome Android Full support YesFirefox Android No support NoOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
onclickChrome Full support YesEdge Full support 14Firefox Full support 22IE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android No support NoOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
oncloseChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
onerrorChrome Full support YesEdge Full support 14Firefox No support NoIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android No support NoOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
onshowChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
permissionChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
renotifyChrome Full support 50Edge No support NoFirefox No support NoIE No support NoOpera Full support 37Safari No support NoWebView Android No support NoChrome Android Full support 50Firefox Android No support NoOpera Android Full support 37Safari iOS No support NoSamsung Internet Android Full support Yes
requireInteractionChrome Full support YesEdge Full support 17Firefox No support NoIE No support NoOpera Full support YesSafari ? WebView Android No support NoChrome Android Full support YesFirefox Android No support NoOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
silentChrome Full support 43Edge Full support 17Firefox No support NoIE No support NoOpera Full support 30Safari No support NoWebView Android No support NoChrome Android Full support 43Firefox Android No support NoOpera Android Full support 30Safari iOS No support NoSamsung Internet Android Full support Yes
tagChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
timestampChrome Full support YesEdge Full support 17Firefox No support NoIE No support NoOpera Full support YesSafari ? WebView Android No support NoChrome Android Full support YesFirefox Android No support NoOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
titleChrome Full support YesEdge Full support 14Firefox No support NoIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android No support NoOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
vibrateChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android Full support 53
Notes
Full support 53
Notes
Notes Does not work on Android O or later regardless of Chrome version.
Firefox Android No support NoOpera Android Full support 41
Notes
Full support 41
Notes
Notes Does not work on Android O or later regardless of Chrome version.
Safari iOS No support NoSamsung Internet Android Full support Yes
Notes
Full support Yes
Notes
Notes Does not work on Android O or later regardless of Chrome version.
closeChrome Full support YesEdge Full support 14Firefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS No support NoSamsung Internet Android Full support Yes
requestPermissionChrome Full support 46Edge Full support 14Firefox Full support 47IE No support NoOpera Full support 40Safari Full support YesWebView Android No support NoChrome Android Full support 46Firefox Android Full support YesOpera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.
Requires a vendor prefix or different name for use.
Requires a vendor prefix or different name for use.

See also