Notifications API Standard Notifications API Living Standard — Last Updated 15 March 2026 Participate: GitHub whatwg/notifications (new issue, open issues) Chat on Matrix Commits: GitHub whatwg/notifications/commits Snapshot as of this commit @notifyapi Tests: web-platform-tests notifications/ (ongoing work) Translations (non-normative): 日本語 简体中文 한국어 Abstract This standard defines an API to display notifications to the end user, typically outside the top-level browsing context’s viewport. It is designed to be compatible with existing notification systems, while remaining platform-independent. 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 navigation URL (null or a URL). It is initially null. 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. navigation URL Null or a URL. It is initially null. 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. To create a notification with a settings object, given a string title, NotificationOptions dictionary options, and environment settings object settings: Let origin be settings’s origin. Let baseURL be settings’s API base URL. Let fallbackTimestamp be the number of milliseconds from the Unix epoch to settings’s current wall time, rounded to the nearest integer. Return the result of creating a notification given title, options, origin, baseURL, and fallbackTimestamp. To create a notification, given a string title, NotificationOptions dictionary options, an origin origin, a URL baseURL, and an EpochTimeStamp fallbackTimestamp: Let notification be a new notification. If options["silent"] is true and options["vibrate"] exists, then throw a TypeError. If options["renotify"] is true and options["tag"] is the empty string, then throw a TypeError. Set notification’s data to StructuredSerializeForStorage(options["data"]). Set notification’s title to title. Set notification’s direction to options["dir"]. Set notification’s language to options["lang"]. Set notification’s origin to origin. Set notification’s body to options["body"]. If options["navigate"] exists, then parse it using baseURL, and if that does not return failure, set notification’s navigation URL to the return value. (Otherwise notification’s navigation URL remains null.) Set notification’s tag to options["tag"]. If options["image"] exists, then parse it using baseURL, and if that does not return failure, set notification’s image URL to the return value. (Otherwise notification’s image URL is not set.) If options["icon"] exists, then parse it using baseURL, and if that does not return failure, set notification’s icon URL to the return value. (Otherwise notification’s icon URL is not set.) If options["badge"] exists, then parse it using baseURL, and if that does not return failure, set notification’s badge URL to the return value. (Otherwise notification’s badge URL is not set.) If options["vibrate"] exists, then validate and normalize it and set notification’s vibration pattern to the return value. If options["timestamp"] exists, then set notification’s timestamp to the value. Otherwise, set notification’s timestamp to fallbackTimestamp. Set notification’s renotify preference to options["renotify"]. Set notification’s silent preference to options["silent"]. Set notification’s require interaction preference to options["requireInteraction"]. Set notification’s actions to « ». For each entry in options["actions"], up to the maximum number of actions supported (skip any excess entries): Let action be a new notification action. Set action’s name to entry["action"]. Set action’s title to entry["title"]. If entry["navigate"] exists, then parse it using baseURL, and if that does not return failure, set action’s navigation URL to the return value. (Otherwise action’s navigation URL remains null.) If entry["icon"] exists, then parse it using baseURL, and if that does not return failure, set action’s icon URL to the return value. (Otherwise action’s icon URL remains null.) Append action to notification’s actions. Return notification. 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] To get the notifications permission state, run these steps: Let permissionState be the result of getting the current permission state with "notifications". If permissionState is "prompt", then return "default". Return permissionState. 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 The fetch steps for a given notification notification are: If the notification platform supports images, fetch notification’s image URL, if image URL is set. The intent is to fetch this resource similar to an <img>, but this needs abstracting. Then, in parallel: Wait for the response. If the response’s internal response’s type is "default", then attempt to decode the resource as image. If the image format is supported, set notification’s image resource to the decoded resource. (Otherwise notification has no image resource.) If the notification platform supports icons, fetch notification’s icon URL, if icon URL is set. The intent is to fetch this resource similar to an <img>, but this needs abstracting. Then, in parallel: Wait for the response. If the response’s internal response’s type is "default", then attempt to decode the resource as image. If the image format is supported, set notification’s icon resource to the decoded resource. (Otherwise notification has no icon…