Notifications API

1. Terminology

This specification depends on the Infra Standard. [INFRA]

Some terms used in this specification are defined in the DOM, Fetch, High Resolution Time, HTML, IDL, Service Workers, URL, and Vibration API Standards. [DOM] [FETCH] [HR-TIME] [HTML] [WEBIDL] [SERVICE-WORKERS] [URL] [VIBRATION]

2. Notifications

A notification is an abstract representation of something that happened, such as the delivery of a message.

A notification has an associated service worker registration (null or a service worker registration). It is initially null.

A notification has an associated title (a string).

A notification has an associated direction ("auto", "ltr", or "rtl").

A notification has an associated language (a string).

A notification has an associated body (a string).

A notification has an associated tag (a string).

A notification has an associated data (a Record).

A notification has an associated timestamp (an EpochTimeStamp).

Timestamps can be used to indicate the time at which a notification is actual. For example, this could be in the past when a notification is used for a message that couldn’t immediately be delivered because the device was offline, or in the future for a meeting that is about to start.

A notification has an associated origin (an origin).

A notification has an associated renotify preference (a boolean). It is initially false. When true, indicates that the end user should be alerted after the notification show steps have run with a new notification that has the same tag as an existing notification.

A notification has an associated silent preference (null or a boolean). It is initially null. When true, indicates that no sounds or vibrations should be made. When null, indicates that producing sounds or vibrations should be left to platform conventions.

A notification has an associated require interaction preference (a boolean). It is initially false. When true, indicates that on devices with a sufficiently large screen, the notification should remain readily available until the end user activates or dismisses the notification.

A notification can have these associated graphics: an image URL, icon URL, and badge URL; and their corresponding image resource, icon resource, and badge resource.

An image resource is a picture shown as part of the content of the notification, and should be displayed with higher visual priority than the icon resource and badge resource, though it may be displayed in fewer circumstances.

An icon resource is an image that reinforces the notification (such as an icon, or a photo of the sender).

A badge resource is an icon representing the web application, or the category of the notification if the web application sends a wide variety of notifications. It may be used to represent the notification when there is not enough space to display the notification itself. It may also be displayed inside the notification, but then it should have less visual priority than the image resource and icon resource.

A notification has an associated vibration pattern (a list). It is initially « ».

Developers are encouraged to not convey information through an image, icon, badge, or vibration pattern that is not otherwise accessible to the end user, especially since notification platforms that do not support these features might ignore them.

A notification has associated actions (a list of zero or more notification actions). A notification action represents a choice for an end user. Each notification action has an associated:

name

A string.

title

A string.

icon URL

Null or a URL. It is initially null.

icon resource

Null or a resource. It is initially null.

Users may activate actions, as alternatives to activating the notification itself. The maximum number of actions supported is an implementation-defined integer of zero or more, within the constraints of the notification platform.

Since display of actions is platform-dependent, developers are encouraged to make sure that any action an end user can invoke from a notification is also available within the web application.

Some platforms might modify an icon resource to better match the platform’s visual style before displaying it to the end user, for example by rounding the corners or painting it in a specific color. Developers are encouraged to use an icon that handles such cases gracefully and does not lose important information through, e.g., loss of color or clipped corners.

A non-persistent notification is a notification whose service worker registration is null.

A persistent notification is a notification whose service worker registration is non-null.

2.1. Lifetime and UI integration

The user agent must keep a list of notifications, which is a list of zero or more notifications.

User agents should run the close steps for a non-persistent notification a couple of seconds after they have been created.

User agents should not display non-persistent notification in a platform’s "notification center" (if available).

User agents should persist persistent notifications until they are removed from the list of notifications.

A persistent notification could have the close() method invoked of one of its Notification objects.

User agents should display persistent notifications in a platform’s "notification center" (if available).

2.2. Permissions integration

The Notifications API is a powerful feature which is identified by the name "notifications". [Permissions]

2.3. Direction

This section is written in terms equivalent to those used in the Rendering section of HTML. [HTML]

User agents are expected to honor the Unicode semantics of the text of a notification’s title, body, and the title of each of its actions. Each is expected to be treated as an independent set of one or more bidirectional algorithm paragraphs when displayed, as defined by the bidirectional algorithm’s rules P1, P2, and P3, including, for instance, supporting the paragraph-breaking behavior of U+000A LINE FEED (LF) characters. For each paragraph of the title, body and the title of each of the actions, the notification’s direction provides the higher-level override of rules P2 and P3 if it has a value other than "auto". [BIDI]

The notification’s direction also determines the relative order in which the notification’s actions should be displayed to the end user, if the notification platform displays them side by side.

2.4. Language

The notification’s language specifies the primary language for the notification’s title, body and the title of each of its actions. Its value is a string. The empty string indicates that the primary language is unknown. Any other string must be interpreted as a language tag. Validity or well-formedness are not enforced. [BCP47]

Developers are encouraged to only use valid language tags.

2.5. Resources

2.6. Showing a notification

2.7. Activating a notification

2.8. Closing a notification

When a notification is closed, either by the underlying notification platform or by the end user, the close steps for it must be run.

2.9. Alerting the end user

3. API

[Exposed=(Window,Worker)]
interface Notification : EventTarget {
  constructor(DOMString title, optional NotificationOptions options = {});

  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);

  static readonly attribute unsigned long maxActions;

  attribute EventHandler onclick;
  attribute EventHandler onshow;
  attribute EventHandler onerror;
  attribute EventHandler onclose;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute DOMString tag;
  readonly attribute USVString image;
  readonly attribute USVString icon;
  readonly attribute USVString badge;
  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
  readonly attribute EpochTimeStamp timestamp;
  readonly attribute boolean renotify;
  readonly attribute boolean? silent;
  readonly attribute boolean requireInteraction;
  [SameObject] readonly attribute any data;
  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;

  undefined close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  DOMString tag = "";
  USVString image;
  USVString icon;
  USVString badge;
  VibratePattern vibrate;
  EpochTimeStamp timestamp;
  boolean renotify = false;
  boolean? silent = null;
  boolean requireInteraction = false;
  any data = null;
  sequence<NotificationAction> actions = [];
};

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};

dictionary NotificationAction {
  required DOMString action;
  required DOMString title;
  USVString icon;
};

callback NotificationPermissionCallback = undefined (NotificationPermission permission);

A non-persistent notification is represented by one Notification object and can be created through Notification's constructor.

A persistent notification is represented by zero or more Notification objects and can be created through the showNotification() method.

3.1. Garbage collection

A Notification object must not be garbage collected while the list of notifications contains its corresponding notification and it has an event listener whose type is click, show, close, or error.

3.2. Constructors

3.3. Static members

const permission = await navigator.permissions.query({name: "notifications"});
if (permission.state === "granted") {
   // We have permission to use the API…
}

Notifications are the one instance thus far where asking the end user upfront makes sense. Specifications for other APIs should not use this pattern and instead employ one of the many more suitable alternatives.

The static maxActions getter steps are to return the maximum number of actions supported.

3.4. Object members

The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the Notification object.

The close() method steps are to run the close steps for this’s notification.

The title getter steps are to return this’s notification’s title.

The dir getter steps are to return this’s notification’s direction.

The lang getter steps are to return this’s notification’s language.

The body getter steps are to return this’s notification’s body.

The tag getter steps are to return this’s notification’s tag.

The image getter steps are:

1. If there is no this’s notification’s image URL, then return the empty string.

2. Return this’s notification’s image URL, serialized.

The icon getter steps are:

1. If there is no this’s notification’s icon URL, then return the empty string.

2. Return this’s notification’s icon URL, serialized.

The badge getter steps are:

1. If there is no this’s notification’s badge URL, then return the empty string.

2. Return this’s notification’s badge URL, serialized.

The vibrate getter steps are to return this’s notification’s vibration pattern.

The timestamp getter steps are to return this’s notification’s timestamp.

The renotify getter steps are to return this’s notification’s renotify preference.

The silent getter steps are to return this’s notification’s silent preference.

The requireInteraction getter steps are to return this’s notification’s require interaction preference.

The data getter steps are to return StructuredDeserialize(this’s notification’s data, this’s relevant Realm). If this throws an exception, then return null.

The actions getter steps are:

1. Let frozenActions be an empty list of type NotificationAction.

2. For each entry of this’s notification’s actions:

   1. Let action be a new NotificationAction.

   2. Set action["action"] to entry’s name.

   3. Set action["title"] to entry’s title.

   4. If entry’s icon URL is non-null, then set action["icon"] to entry’s icon URL, serialized.

   5. Call Object.freeze on action, to prevent accidental mutation by scripts.

   6. Append action to frozenActions.

3. Return the result of create a frozen array from frozenActions.

3.5. Examples

3.5.1. Using events from a page

Non-persistent Notification objects dispatch events during their lifecycle, which developers can use to generate desired behaviors.

The click event dispatches when the end user activates a notification.

var not = new Notification("Gebrünn Gebrünn by Paul Kalkbrenner", { icon: "newsong.svg", tag: "song" });
not.onclick = function() { displaySong(this); };

3.5.2. Using actions from a service worker

Persistent notifications fire notificationclick events on the ServiceWorkerGlobalScope.

Here a service worker shows a notification with a single "Archive" notification action, allowing end users to perform this common task from the notification without having to open the website (for example, the notification platform might show a button on the notification). The end user can also activate the main body of the notification to open their inbox.

self.registration.showNotification("New mail from Alice", {
  actions: [{action: 'archive', title: "Archive"}]
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  if (event.action === 'archive') {
    silentlyArchiveEmail();
  } else {
    clients.openWindow("/inbox");
  }
}, false);

3.5.3. Using the tag member for multiple instances

Web applications frequently operate concurrently in multiple instances, such as when an end user opens a mail application in multiple browser tabs. Since the desktop is a shared resource, the notifications API provides a way for these instances to easily coordinate, by using the tag member.

Notifications which represent the same conceptual event can be tagged in the same way, and when both are shown, the end user will only receive one notification.

Instance 1                                   | Instance 2
                                             |
// Instance notices there is new mail.       |
new Notification("New mail from John Doe",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // Slightly later, this instance notices
                                             |  // there is new mail.
                                             |  new Notification("New mail from John Doe",
                                             |                   { tag: 'message1' });

The result of this situation, if the user agent follows the algorithms here, is a single notification "New mail from John Doe".

3.5.4. Using the tag member for a single instance

The tag member can also be used by a single instance of an application to keep its notifications as current as possible as state changes.

For example, if Alice is using a chat application with Bob, and Bob sends multiple messages while Alice is idle, the application may prefer that Alice not see a desktop notification for each message.

// Bob says "Hi"
new Notification("Bob: Hi", { tag: 'chat_Bob' });

// Bob says "Are you free this afternoon?"
new Notification("Bob: Hi / Are you free this afternoon?", { tag: 'chat_Bob' });

The result of this situation is a single notification; the second one replaces the first having the same tag. In a platform that queues notifications (first-in-first-out), using the tag allows the notification to also maintain its position in the queue. Platforms where the newest notifications are shown first, a similar result could be achieved using the close() method.

4. Service worker API

dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise<undefined> showNotification(DOMString title, optional NotificationOptions options = {});
  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter = {});
};

[Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  constructor(DOMString type, NotificationEventInit eventInitDict);

  readonly attribute Notification notification;
  readonly attribute DOMString action;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
  DOMString action = "";
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
  attribute EventHandler onnotificationclose;
};

The following is the event handler (and its corresponding event handler event type) that must be supported as attribute by the ServiceWorkerGlobalScope object:

Acknowledgments

Thanks to Addison Phillips, Aharon (Vladimir) Lanin, Alex Russell, Anssi Kostiainen, Arkadiusz Michalski, Boris Zbarsky, David Håsäther, Doug Turner, Drew Wilson, Ehsan Akhgari, Frederick Hirsch, Ian Hickson, Jake Archibald, James Graham, John Mellor, Jon Lee, Jonas Sicking, Michael Cooper, Michael Henretty, Michael™ Smith, Michael van Ouwerkerk, Mike Taylor, Nicolás Satragno, Olli Pettay, Peter Beverloo, Philip Jägenstedt, Reuben Morais, Rich Tibbett, Robert Bindar, 박상현 (Sanghyun Park), Simon Pieters, Theresa O’Connor, timeless, and triple-underscore for being awesome.

This standard is written by Anne van Kesteren (Apple, [email protected]). An earlier iteration was written by John Gregg (Google, [email protected]).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.

This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft.