Notification

  • Revision slug: Web/API/notification
  • Revision title: Notification
  • Revision id: 513935
  • Created:
  • Creator: Sole
  • Is current revision? No
  • Comment update link to Notification shim

Revision Content

{{ domref() }}

{{ SeeCompatTable() }}

Summary

The Notification object is used to configure and display desktop notifications to the user.

Constructor

var notification = new Notification(title, options)

Parameters

title
The title that must be shown within the notification
options {{optional_inline}}
An object that allows to configure the notification. It can have the following properties:
dir : The direction of the notification; it can be auto, ltr, or rtl
lang: Specifiy the lang used within the notification. This string must be a valid BCP 47 language tag.
body: A string representing an extra content to display within the notification
tag: An ID for a given notification that allows to retrieve, replace or remove it if necessary
icon: The URL of an image to be used as an icon by the notification

Properties

Static properties

Those properties are available only on the Notification object itself.

{{domxref("Notification.permission")}} {{readonlyinline}}
A string representing the current permission to display notifications. Possible value are: denied (the user refuses to have notifications displayed), granted (the user accepts to have notifications displayed), or default (the user choice is unknown and therefore the browser will act as if the value was denied).

Instance properties

Those properties are available only on instances of the Notification object.

{{domxref("Notification.dir")}} {{readonlyinline}}
The direction used by the notification as defined within the constructor options.
{{domxref("Notification.lang")}} {{readonlyinline}}
The code lang used by the notification as defined within the constructor options.
{{domxref("Notification.body")}} {{readonlyinline}}
The body string used by the notification as defined within the constructor options.
{{domxref("Notification.tag")}} {{readonlyinline}}
The id of the notification (if any) as defined within the constructor options.
{{domxref("Notification.icon")}} {{readonlyinline}}
The URL of the image used as an icon as defined within the constructor options.

Event handlers

{{domxref("Notification.onclick")}}
A handler for the {{event("click")}} event. It is triggered each time the user clicks on the notification.
{{domxref("Notification.onshow")}}
A handler for the {{event("show")}} event. It is triggered when the notification is displayed.
{{domxref("Notification.onerror")}}
A handler for the {{event("error")}} event. It is triggered each time the notification encounters an error.
{{domxref("Notification.onclose")}}
A handler for the {{event("close")}} event. It is triggered when the user closes the notification.

Methods

Static methods

Those methods are available only on the Notification object itself.

{{domxref("Notification.requestPermission()")}}
This method is used to ask the user if he allows the page to display notifications.

Instance methods

Those properties are available only on an instance of the Notification object or through its prototype.

{{domxref("Notification.close()")}}
This method allows to programmatically close a notification.

The Notification objects also inherit from the {{domxref("EventTarget")}} interface.

{{page("/en-US/docs/Web/API/EventTarget","Methods")}}

Example

Assume this basic HTML:

<button onclick="notifyMe()">Notify me!</button>

It's possible to send a notification as follows:

function notifyMe() {
  // Let's check if the browser supports notifications
  if (!("Notification" in window)) {
    alert("This browser does not support desktop notification");
  }

  // Let's check if the user is okay to get some notification
  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
  // Note, Chrome does not implement the permission static property
  // So we have to check for NOT 'denied' instead of 'default'
  else if (Notification.permission !== 'denied') {
    Notification.requestPermission(function (permission) {

      // Whatever the user answers, we make sure Chrome stores the information
      if(!('permission' in Notification)) {
        Notification.permission = permission;
      }

      // If the user is okay, let's create a notification
      if (permission === "granted") {
        var notification = new Notification("Hi there!");
      }
    });
  }

  // At last, if the user already denied any notification, and you 
  // want to be respectful there is no need to bother him any more.
}

See the live result

{{ EmbedLiveSample('Example', '100%', 30) }}

Specifications

Specification Status Comment
{{SpecName('Web Notifications')}} {{Spec2('Web Notifications')}} Initial specification.

Permissions

When using notifications  in an open web app, be sure to add the desktop-notification permission in your manifest file:

"permissions": {
    "desktop-notification":{}
}

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 5 {{ property_prefix("webkit") }} (see notes)
22
4.0 {{ property_prefix("moz") }} (see notes)
22
{{ CompatNo() }} {{ CompatUnknown() }} 6 (see notes)
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} 4.0 {{ property_prefix("moz") }} (see notes)
22
{{ CompatNo() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Gecko notes

  • Prior to Firefox 22 (Firefox OS <1.2), the instantiation of a new notification must be done with the {{ domxref("window.navigator.mozNotification","navigator.mozNotification") }} object through its createNotification method.
  • Prior to Firefox 22 (Firefox OS <1.2), the Notification was displayed when calling the show method and was supporting the click and close events only.
  • Nick Desaulniers has written a Notification shim to cover both newer and older implementations.
  • One particular Firefox OS issue is that you can pass a path to an icon to use in the notification, but if the app is packaged you cannot use a relative path like /my_icon.png. You also can't use navigator.location.origin + "/my_icon.png" because navigator.location.origin is null in packaged apps. The manifest origin field fixes this, but it is only available in Firefox OS 1.1+. A potential solution for supporting Firefox OS <1.1 is to pass an absolute URL to an externally hosted version of the icon. This is less than ideal as the notification is displayed immediately with the icon missing, then the icon is fetched, but it works on all versions of Firefox OS.

Chrome notes

  • Prior to Chrome 22, the support for notification was following an old prefixed version of the specification and was using the {{domxref("window.navigator.webkitNotifications","navigator.webkitNotifications")}} object to instantiate a new notification.
  • Prior to Chrome 32, {{domxref("Notification.permission")}} was not supported.

Safari notes

  • Safari started supporting notification with Safari 6 but only on Mac OSX 10.8+ (Mountain Lion).

See also

Revision Source

<p>{{ domref() }}</p>
<p>{{ SeeCompatTable() }}</p>
<h2 id="Summary">Summary</h2>
<p>The <code>Notification</code> object is used to configure and display desktop notifications to the user.</p>
<h2 id="Method_overview" name="Method_overview">Constructor</h2>
<pre>
var notification = new Notification(title, options)</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
 <dt>
  <code>title</code></dt>
 <dd>
  The title that must be shown within the notification</dd>
 <dt>
  <code>options</code> {{optional_inline}}</dt>
 <dd>
  An object that allows to configure the notification. It can have the following properties:<br />
  <code>dir</code> : The direction of the notification; it can be <code>auto</code>, <code>ltr</code>, or <code>rtl</code><br />
  <code>lang</code>: Specifiy the lang used within the notification. This string must be a valid <a href="http://tools.ietf.org/html/bcp47" title="http://tools.ietf.org/html/bcp47">BCP 47 language tag</a>.<br />
  <code>body</code>: A string representing an extra content to display within the notification<br />
  <code>tag</code>: An ID for a given notification that allows to retrieve, replace or remove it if necessary<br />
  <code>icon</code>: The URL of an image to be used as an icon by the notification</dd>
</dl>
<h2 id="Properties">Properties</h2>
<h3 id="Static_properties">Static properties</h3>
<p>Those properties are available only on the <code>Notification</code> object itself.</p>
<dl>
 <dt>
  {{domxref("Notification.permission")}} {{readonlyinline}}</dt>
 <dd>
  A string representing the current permission to display notifications. Possible value are: <code>denied</code> (the user refuses to have notifications displayed), <code>granted</code> (the user accepts to have notifications displayed), or <code>default</code> (the user choice is unknown and therefore the browser will act as if the value was denied).</dd>
</dl>
<h3 id="Instance_properties">Instance properties</h3>
<p>Those properties are available only on instances of the <code>Notification</code> object.</p>
<dl>
 <dt>
  {{domxref("Notification.dir")}} {{readonlyinline}}</dt>
 <dd>
  The direction used by the notification as defined within the constructor options.</dd>
 <dt>
  {{domxref("Notification.lang")}} {{readonlyinline}}</dt>
 <dd>
  The code lang used by the notification as defined within the constructor options.</dd>
 <dt>
  {{domxref("Notification.body")}} {{readonlyinline}}</dt>
 <dd>
  The body string used by the notification as defined within the constructor options.</dd>
 <dt>
  {{domxref("Notification.tag")}} {{readonlyinline}}</dt>
 <dd>
  The id of the notification (if any) as defined within the constructor options.</dd>
 <dt>
  {{domxref("Notification.icon")}} {{readonlyinline}}</dt>
 <dd>
  The URL of the image used as an icon as defined within the constructor options.</dd>
</dl>
<h4 id="Event_handlers">Event handlers</h4>
<dl>
 <dt>
  {{domxref("Notification.onclick")}}</dt>
 <dd>
  A handler for the {{event("click")}} event. It is triggered each time the user clicks on the notification.</dd>
 <dt>
  {{domxref("Notification.onshow")}}</dt>
 <dd>
  A handler for the {{event("show")}} event. It is triggered when the notification is displayed.</dd>
 <dt>
  {{domxref("Notification.onerror")}}</dt>
 <dd>
  A handler for the {{event("error")}} event. It is triggered each time the notification encounters an error.</dd>
 <dt>
  {{domxref("Notification.onclose")}}</dt>
 <dd>
  A handler for the {{event("close")}} event. It is triggered when the user closes the notification.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<h3 id="Static_methods">Static methods</h3>
<p>Those methods are available only on the <code>Notification</code> object itself.</p>
<dl>
 <dt>
  {{domxref("Notification.requestPermission()")}}</dt>
 <dd>
  This method is used to ask the user if he allows the page to display notifications.</dd>
</dl>
<h3 id="Instance_methods">Instance methods</h3>
<p>Those properties are available only on an instance of the <code>Notification</code> object or through its <a href="/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain" title="/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain"><code>prototype</code></a>.</p>
<dl>
 <dt>
  {{domxref("Notification.close()")}}</dt>
 <dd>
  This method allows to programmatically close a notification.</dd>
</dl>
<p>The <code>Notification</code> objects also inherit from the {{domxref("EventTarget")}} interface.</p>
<p>{{page("/en-US/docs/Web/API/EventTarget","Methods")}}</p>
<h2 id="Example">Example</h2>
<p>Assume this basic HTML:</p>
<pre class="brush: html">
&lt;button onclick="notifyMe()"&gt;Notify me!&lt;/button&gt;</pre>
<p>It's possible to send a notification as follows:</p>
<pre class="brush: js">
function notifyMe() {
  // Let's check if the browser supports notifications
  if (!("Notification" in window)) {
    alert("This browser does not support desktop notification");
  }

  // Let's check if the user is okay to get some notification
  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
  // Note, Chrome does not implement the permission static property
  // So we have to check for NOT 'denied' instead of 'default'
  else if (Notification.permission !== 'denied') {
    Notification.requestPermission(function (permission) {

      // Whatever the user answers, we make sure Chrome stores the information
      if(!('permission' in Notification)) {
        Notification.permission = permission;
      }

      // If the user is okay, let's create a notification
      if (permission === "granted") {
        var notification = new Notification("Hi there!");
      }
    });
  }

  // At last, if the user already denied any notification, and you 
  // want to be respectful there is no need to bother him any more.
}</pre>
<h3 id="See_the_live_result">See the live result</h3>
<p>{{ EmbedLiveSample('Example', '100%', 30) }}</p>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('Web Notifications')}}</td>
   <td>{{Spec2('Web Notifications')}}</td>
   <td>Initial specification.</td>
  </tr>
 </tbody>
</table>
<h2 id="Methods" name="Methods">Permissions</h2>
<p>When using notifications&nbsp; in an open web app, be sure to add the <code>desktop-notification</code> permission in your manifest file:</p>
<pre class="default prettyprint prettyprinted" style="">
<code><span class="str">"permissions"</span><span class="pun">:</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
    </span><span class="str">"desktop-notification"</span><span class="pun">:{}</span><span class="pln">
</span><span class="pun">}</span></code></pre>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Chrome</th>
    <th>Firefox (Gecko)</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>5 {{ property_prefix("webkit") }} (see notes)<br />
     22</td>
    <td>4.0 {{ property_prefix("moz") }} (see notes)<br />
     22</td>
    <td>{{ CompatNo() }}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>6 (see notes)</td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Android</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>IE Mobile</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{ CompatUnknown() }}</td>
    <td>4.0 {{ property_prefix("moz") }} (see notes)<br />
     22</td>
    <td>{{ CompatNo() }}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
   </tr>
  </tbody>
 </table>
</div>
<h3 id="Gecko_notes">Gecko notes</h3>
<ul>
 <li>Prior to Firefox 22 (Firefox OS &lt;1.2), the instantiation of a new notification must be done with the {{ domxref("window.navigator.mozNotification","navigator.mozNotification") }} object through its <code>createNotification</code> method.</li>
 <li>Prior to Firefox 22 (Firefox OS &lt;1.2), the Notification was displayed when calling the <code>show</code> method and was supporting the <code>click</code> and <code>close</code> events only.</li>
 <li>Nick Desaulniers has written a <a href="https://github.com/nickdesaulniers/fxos-irc/blob/master/js/notification.js">Notification shim</a> to cover both newer and older implementations.</li>
 <li>One particular Firefox OS issue is that you can <a href="https://github.com/nickdesaulniers/fxos-irc/blob/0160cf6c3a2b5c9fe33822aaf6bcba3b7e846da9/my.js#L171">pass a path to an icon</a> to use in the notification, but if the app is packaged you cannot use a relative path like <code>/my_icon.png</code>. You also can't use <code>navigator.location.origin + "/my_icon.png"</code> because <code>navigator.location.origin</code> is null in packaged apps. The <a href="https://developer.mozilla.org/en-US/Apps/Developing/Manifest#origin">manifest origin field</a> fixes this, but it is only available in Firefox OS 1.1+. A potential solution for supporting Firefox OS &lt;1.1 is to <a href="https://github.com/nickdesaulniers/fxos-irc/blob/0160cf6c3a2b5c9fe33822aaf6bcba3b7e846da9/my.js#L168">pass an absolute URL to an externally hosted version of the icon</a>. This is less than ideal as the notification is displayed immediately with the icon missing, then the icon is fetched, but it works on all versions of Firefox OS.</li>
</ul>
<h3 id="Chrome_notes">Chrome notes</h3>
<ul>
 <li>Prior to Chrome 22, the support for notification was following an <a href="http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification" title="http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification">old prefixed version of the specification</a> and was using the {{domxref("window.navigator.webkitNotifications","navigator.webkitNotifications")}} object to instantiate a new notification.</li>
 <li>Prior to Chrome 32, {{domxref("Notification.permission")}} was not supported.</li>
</ul>
<h3 id="Safari_notes">Safari notes</h3>
<ul>
 <li>Safari started supporting notification with Safari 6 but only on Mac OSX 10.8+ (Mountain Lion).</li>
</ul>
<h2 id="See_also">See also</h2>
<ul>
 <li><a href="/en-US/docs/WebAPI/Using_Web_Notifications" title="/en-US/docs/WebAPI/Using_Web_Notifications">Using Web Notifications</a></li>
</ul>
Revert to this revision