Document Notification.navigate property

files/en-us/web/api/notification/index.md

@@ -51,6 +51,8 @@ _Also inherits properties from its parent interface, {{domxref("EventTarget")}}_
   - : The URL of an image to be displayed as part of the notification, as specified in the constructor's `options` parameter.
 - {{domxref("Notification.lang")}} {{ReadOnlyInline}}
   - : The language code of the notification as specified in the constructor's `options` parameter.
+- {{domxref("Notification.navigate")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : The navigation URL of the notification. When set, activating the notification navigates to this URL instead of firing the {{domxref("Notification.click_event", "click")}} or {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} event.
 - {{domxref("Notification.renotify")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : Specifies whether the user should be notified after a new notification replaces an old one.
 - {{domxref("Notification.requireInteraction")}} {{ReadOnlyInline}}

files/en-us/web/api/notification/navigate/index.md

@@ -0,0 +1,69 @@
+---
+title: "Notification: navigate property"
+short-title: navigate
+slug: Web/API/Notification/navigate
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.Notification.navigate
+---
+
+{{APIRef("Web Notifications")}}{{securecontext_header}}{{SeeCompatTable}} {{AvailableInWorkers}}
+
+The **`navigate`** read-only property of the {{domxref("Notification")}} interface contains the URL the user agent will navigate to when the user activates the notification.
+
+This is the resolved value of the URL, if any, that was specified in the `navigate` option of the {{domxref("Notification.Notification", "Notification()")}} constructor or {{domxref("ServiceWorkerRegistration.showNotification()")}}.
+
+Normally, activating a non-persistent notification fires the {{domxref("Notification.click_event", "click")}} event on its {{domxref("Notification")}} object, and activating a persistent notification fires the {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} event on the {{domxref("ServiceWorkerGlobalScope")}}.
+
+When a notification with a navigation URL is activated by the user, the user agent navigates to the specified URL instead of firing either of these events. This allows notifications to direct users to a specific page without requiring an event handler.
+
+## Value
+
+A string containing a {{glossary("URL")}}, or an empty string if no navigation URL has been set.
+
+## Examples
+
+### Reading the navigate property value
+
+The `navigate` property returns the resolved URL string when a navigation URL has been set, or an empty string otherwise.
+
+```js
+const notification = new Notification("New message from Alice", {
+  body: "Hey, are you free for lunch?",
+  navigate: "/messages/alice",
+});
+
+// The property contains the resolved absolute URL
+console.log(notification.navigate); // e.g. "https://example.com/messages/alice"
+
+// Without a navigate option, the property is an empty string
+const basic = new Notification("Hello!");
+console.log(basic.navigate); // ""
+```
+
+### Using navigate with a service worker
+
+When using persistent notifications through a service worker, the `navigate` option allows the notification to open a page when activated, without needing to handle the {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} event.
+
+```js
+// Inside a service worker
+self.registration.showNotification("Order shipped!", {
+  body: "Your order #1234 has been shipped.",
+  navigate: "/orders/1234",
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using the Notifications API](/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API)
+- {{domxref("Notification.Notification", "Notification()")}} constructor
+- {{domxref("ServiceWorkerRegistration.showNotification()")}}

files/en-us/web/api/notification/notification/index.md

@@ -12,7 +12,7 @@ The **`Notification()`** constructor creates a new {{domxref("Notification")}} o
 
 Trying to create a notification inside the {{domxref("ServiceWorkerGlobalScope")}} using the `Notification()` constructor will throw a `TypeError`. Use {{domxref("ServiceWorkerRegistration.showNotification()")}} instead.
 
-You must first get permission before being able to display notifications, using {{domxref("Notification.requestPermission()")}}. The permission may not be grantable, for example if the page is in private browsing mode.
+You must first get permission before being able to display notifications, using {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}}. The permission may not be grantable, for example if the page is in private browsing mode.
 
 This constructor throws a {{jsxref("TypeError")}} when called in nearly all mobile browsers and this is unlikely to change, because web pages on mobile devices almost never "run in the background", which is the main use case for notifications. Instead, you need to register a service worker and use {{domxref("ServiceWorkerRegistration.showNotification()")}}. See [Chrome issue](https://crbug.com/481856) for more information.
 
@@ -45,6 +45,8 @@ new Notification(title, options)
       - : A string containing the URL of an image to be displayed in the notification.
     - `lang` {{optional_inline}}
       - : The notification's language, as specified using a string representing a {{glossary("BCP 47 language tag")}}. The default is the empty string.
+    - `navigate` {{optional_inline}} {{experimental_inline}}
+      - : A string containing a URL to navigate to when the user activates the notification. When set, the user agent navigates to this URL instead of firing the {{domxref("Notification.click_event", "click")}} event. The value is parsed relative to the base URL of the page. See {{domxref("Notification.navigate")}} for more information.
     - `renotify` {{optional_inline}}
       - : A boolean value specifying whether the user should be notified after a new notification replaces an old one. The default is `false`, which means they won't be notified. If `true`, then `tag` also must be set.
     - `requireInteraction` {{optional_inline}}

files/en-us/web/api/notifications_api/index.md

@@ -15,8 +15,14 @@ The Notifications API allows web pages to control the display of system notifica
 
 ## Concepts and usage
 
-On supported platforms, showing a system notification generally involves two things. First, the user needs to grant the current origin permission to display system notifications, which is generally done when the app or site initializes, using the {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}} method.
-This method should only be called when handling a user gesture, such as when handling a mouse click. For example:
+Showing a system notification generally involves first requesting permission to use the feature, and then creating a notification.
+
+### Notifications require user permission
+
+In order to use notifications, the user needs to grant the current origin permission to display system notifications.
+This is generally done when the app or site initializes, using the {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}} method.
+This method should only be called when handling a user gesture, such as when handling a mouse click.
+For example:
 
 ```js
 btn.addEventListener("click", () => {
@@ -31,24 +37,48 @@ This will spawn a request dialog, along the following lines:
 
 From here the user can choose to allow notifications from this origin, or block them. Once a choice has been made, the setting will generally persist for the current session.
 
-Next, a new notification is created using the {{domxref("Notification.Notification","Notification()")}} constructor. This must be passed a title argument, and can optionally be passed an options object to specify options, such as text direction, body text, icon to display, notification sound to play, and more.
+### Notification display and handling
+
+Notifications are created using the {{domxref("Notification.Notification","Notification()")}} constructor.
+This must be passed a title argument, and can optionally be passed an options object to specify options, such as text direction, body text, icon to display, notification sound to play, and more.
+
+For example, the following code shows how you might create a notification that sets the [`navigate`](/en-US/docs/Web/API/Notification/Notification#navigate) option, specifying a URL that will be opened if the notification is accepted (you can also defined click handlers to process notification actions).
+
+```js
+if (Notification.permission === "granted") {
+  const notification = new Notification("New message from Alice", {
+    body: "Hey, are you free for lunch?",
+    navigate: "/messages/alice",
+  });
+}
+```
+
+For more usage examples see [Using the Notifications API](/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API).
+
+### Persistent and non-persistent notifications
+
+The Notifications API supports two types of notifications:
+
+- **Non-persistent notifications** are created in a browsing context, such as a web page or tab.
+  Their lifetime is tied to the lifetime of the page — if the page is closed, the notification can no longer be interacted with.
+
+  They are created using the {{domxref("Notification.Notification","Notification()")}} constructor and fire events such as {{domxref("Notification/click_event", "click")}} directly on the `Notification` instance
 
-In addition, the Notifications API spec specifies a number of additions to the [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API), to allow service workers to fire notifications.
+- **Persistent notifications** are created from a service worker, and can remain interactive beyond the lifetime of an individual page.
 
-> [!NOTE]
-> To find out more about using notifications in your own app, read [Using the Notifications API](/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API).
+  They are created using {{domxref("ServiceWorkerRegistration.showNotification()")}} from a service worker and fire {{domxref("ServiceWorkerGlobalScope/notificationclick_event", "notificationclick")}} and {{domxref("ServiceWorkerGlobalScope/notificationclose_event", "notificationclose")}} events on the {{domxref("ServiceWorkerGlobalScope")}}.
 
 ## Interfaces
 
 - {{domxref("Notification")}}
-  - : Defines a notification object.
+  - : Defines a notification object. When activated, a non-persistent notification fires a {{domxref("Notification.click_event", "click")}} event, unless a {{domxref("Notification.navigate", "navigate")}} URL is set, in which case the user agent navigates to that URL instead.
 - {{domxref("NotificationEvent")}}
   - : Represents a notification event dispatched on the {{domxref("ServiceWorkerGlobalScope")}} of a {{domxref("ServiceWorker")}}.
 
 ### Extensions to other interfaces
 
 - {{domxref("ServiceWorkerGlobalScope/notificationclick_event", "notificationclick")}} event
-  - : Occurs when a user clicks on a displayed notification.
+  - : Occurs when a user clicks on a displayed persistent notification, unless a {{domxref("Notification.navigate", "navigate")}} URL is set.
 - {{domxref("ServiceWorkerGlobalScope/notificationclose_event", "notificationclose")}} event
   - : Occurs when a user closes a displayed notification.
 - {{domxref("ServiceWorkerRegistration.getNotifications()")}}

files/en-us/web/api/notifications_api/using_the_notifications_api/index.md

@@ -140,6 +140,13 @@ There are four events that are triggered on the {{domxref("Notification")}} inst
 
 These events can be tracked using the {{domxref("Notification.click_event","onclick")}}, {{domxref("Notification.close_event","onclose")}}, {{domxref("Notification.error_event","onerror")}}, and {{domxref("Notification.show_event","onshow")}} handlers. Because {{domxref("Notification")}} also inherits from {{domxref("EventTarget")}}, it's possible to use the {{domxref("EventTarget.addEventListener","addEventListener()")}} method on it.
 
+> [!NOTE]
+> The events listed above apply to non-persistent notifications created with the {{domxref("Notification.Notification", "Notification()")}} constructor. Persistent notifications created via {{domxref("ServiceWorkerRegistration.showNotification()")}} instead fire the {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} and {{domxref("ServiceWorkerGlobalScope.notificationclose_event", "notificationclose")}} events on the {{domxref("ServiceWorkerGlobalScope")}}.
+
+### Navigating on activation
+
+Instead of handling click events, you can set the {{domxref("Notification.navigate", "navigate")}} option to automatically open a URL when the user activates the notification. This bypasses both the `click` and `notificationclick` events. See {{domxref("Notification.navigate")}} for details.
+
 ## 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.

files/en-us/web/api/serviceworkerregistration/shownotification/index.md

@@ -33,6 +33,8 @@ showNotification(title, options)
           - : A string containing action text to be shown to the user.
         - `icon` {{optional_inline}}
           - : A string containing the URL of an icon to display with the action.
+        - `navigate` {{optional_inline}} {{experimental_inline}}
+          - : A string containing a URL to navigate to when the user activates this action. When set, the user agent navigates to this URL instead of firing the {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} event. See {{domxref("Notification.navigate")}} for more information.
 
         Appropriate responses are built using `event.action` within the {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} event.
 
@@ -50,6 +52,8 @@ showNotification(title, options)
       - : A string containing the URL of an image to be displayed in the notification.
     - `lang` {{optional_inline}}
       - : The notification's language, as specified using a string representing a {{glossary("BCP 47 language tag")}}. The default is the empty string.
+    - `navigate` {{optional_inline}} {{experimental_inline}}
+      - : A string containing a URL to navigate to when the user activates the notification. When set, the user agent navigates to this URL instead of firing the {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} event. The value is parsed relative to the base URL of the service worker. See {{domxref("Notification.navigate")}} for more information.
     - `renotify` {{optional_inline}} {{experimental_inline}}
       - : A boolean value specifying whether the user should be notified after a new notification replaces an old one. The default is `false`, which means they won't be notified. If `true`, then `tag` also must be set.
     - `requireInteraction` {{optional_inline}} {{experimental_inline}}