Notifications API Standard

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
notification
is an abstract
representation of something that happened, such as the delivery of a message.
notification
has an associated
service worker registration
(null
or a
service worker registration
). It is initially null.
notification
has an associated
title
(a string).
notification
has an associated
direction
("
auto
", "
ltr
",
or "
rtl
").
notification
has an associated
language
(a string).
notification
has an associated
body
(a
string).
notification
has an associated
navigation URL
(null or a
URL
). It is initially null.
notification
has an associated
tag
(a string).
notification
has an associated
data
(a
Record
).
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.
notification
has an associated
origin
(an
origin
).
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.
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.
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.
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).
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
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.
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.
non-persistent notification
is a
notification
whose
service worker registration
is null.
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
TypeError
If
options
["
renotify
"] is true and
options
["
tag
"] is the empty string, then
throw
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
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

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

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 resource
.)
If the notification platform supports badges,
fetch
notification
’s
badge URL
, if
badge URL
is set.
The intent is to fetch this resource similar to an

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
badge resource
to the decoded resource. (Otherwise
notification
has no
badge resource
.)
If the notification platform supports actions and action icons, then for each
action
in
notification
’s
actions
: if
icon URL
is non-null,
fetch
action
’s
icon URL
The intent is to fetch this resource similar to an

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, then set
action
’s
icon resource
to the decoded resource. (Otherwise
action
’s
icon resource
remains null.)
2.6.
Showing a notification
The
notification show steps
for a given
notification
notification
are:
Run the
fetch steps
for
notification
Wait for any
fetches
to complete and
notification
’s
image resource
icon resource
, and
badge resource
to be set (if any), as well as the
icon resources
for the
notification
’s
actions
(if any).
Let
shown
be false.
Let
oldNotification
be the
notification
in the
list of notifications
whose
tag
is not the empty string and is
notification
’s
tag
, and whose
origin
is
same origin
with
notification
’s
origin
, if any, and null
otherwise.
If
oldNotification
is non-null:
Handle close events
with
oldNotification
If the notification platform supports replacement:
Replace
oldNotification
with
notification
, in the
list of notifications
Set
shown
to true.
Notification platforms are strongly encouraged to support native
replacement as it leads to a better user experience.
Otherwise,
remove
oldNotification
from the
list of notifications
If
shown
is false:
Append
notification
to the
list of notifications
Display
notification
on the device (e.g., by calling the appropriate
notification platform API).
If
shown
is false or
oldNotification
is non-null, and
notification
’s
renotify preference
is true, then run the
alert steps
for
notification
If
notification
is a
non-persistent notification
, then
queue a task
to
fire an event
named
show
on the
Notification
object representing
notification
2.7.
Activating a notification
When a
notification
notification
, or one of its
actions
, is activated by the end user, assuming the underlying notification
platform supports activation, the user agent must (unless otherwise specified) run these steps:
Let
action
be null.
If one of
notification
’s
actions
was activated by the end
user, then set
action
to that
notification action
Let
navigationURL
be
notification
’s
navigation URL
If
action
is non-null, then set
navigationURL
to
action
’s
navigation URL
This intentionally makes it so that when a
notification action
’s
navigation URL
is null, it falls through to the
click
event, providing more flexibility to the web developer.
If
navigationURL
is non-null:
Select one of the following two options in an
implementation-defined
manner:
Navigate
an existing
top-level traversable
within the user
agent’s
top-level traversable set
to
navigationURL
Create a fresh top-level traversable
given
navigationURL
User agents are strongly encouraged to match platform conventions.
Return.
If
notification
is a
persistent notification
Let
actionName
be the empty string.
If
action
is non-null, then set
actionName
to
action
’s
name
Fire a service worker notification event
named "
notificationclick
" given
notification
and
actionName
Otherwise,
queue a task
to run these steps:
Let
intoFocus
be the result of
firing an event
named
click
on the
Notification
object representing
notification
, with its
cancelable
attribute initialized to true.
User agents are encouraged to make
focus()
work from within the event
listener for the event named
click
If
intoFocus
is true, then the user agent should bring the
notification
’s related
browsing context
’s viewport into focus.
Throughout the web platform "activate" is intentionally misnamed as "click".
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.
The
close steps
for a given
notification
notification
are:
If the
list of notifications
does not
contain
notification
, then abort these steps.
Handle close events
with
notification
Remove
notification
from the
list of notifications
To
handle close events
given a
notification
notification
If
notification
is a
persistent notification
and
notification
was closed by the end user, then
fire a service worker notification event
named
notificationclose
" given
notification
If
notification
is a
non-persistent notification
, then
queue a task
to
fire an event
named
close
on the
Notification
object representing
notification
2.9.
Alerting the end user
The
alert steps
for alerting the end user about a given
notification
notification
are:
Perform vibration
using
notification
’s
vibration pattern
, if any.
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
USVString
navigate
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
= "";
USVString
navigate
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
navigate
USVString
icon
};
callback
NotificationPermissionCallback
undefined
NotificationPermission
permission
);
non-persistent notification
is represented by one
Notification
object and can be created through
Notification
’s
constructor
persistent notification
is represented by zero or more
Notification
objects and can be created through the
showNotification()
method.
3.1.
Garbage collection
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
The
new Notification(
title
options
constructor steps are:
If
this
’s
relevant global object
is a
ServiceWorkerGlobalScope
object,
then
throw
TypeError
If
options
["
actions
"] is not
empty
, then
throw
TypeError
Actions
are only supported for
persistent notifications
Let
notification
be the result of
creating a notification with a settings object
given
title
options
and
this
’s
relevant settings object
Associate
this
with
notification
Run these steps
in parallel
If the result of
getting the notifications permission state
is not
granted
", then
queue a task
to
fire an event
named
error
on
this
, and abort these steps.
Run the
notification show steps
for
notification
3.3.
Static members
The static
permission
getter steps are to
return the result of
getting the notifications permission state
If you edit standards please refrain from copying the above. Synchronous permissions are like
synchronous IO, a bad idea.
Developers are encouraged to use the Permissions
query()
method
instead.
[Permissions]
const permission = await navigator.permissions.query({name: "notifications"});
if (permission.state === "granted") {
// We have permission to use the API…
The static
requestPermission(
deprecatedCallback
method steps are:
Let
global
be the
current global object
Let
promise
be
a new promise
in
this
’s
relevant Realm
Run these steps
in parallel
Let
permissionState
be the result of
requesting permission to use
notifications
".
Queue a global task
on the
DOM manipulation task source
given
global
to run these steps:
If
deprecatedCallback
is given, then
invoke
deprecatedCallback
with «
permissionState
» and "
report
".
Resolve
promise
with
permissionState
Return
promise
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.
event handler
event handler event type
onclick
click
onshow
show
onerror
error
onclose
close
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
navigate
getter steps are:
If
this
’s
notification
’s
navigation URL
is null, then
return the empty string.
Return
this
’s
notification
’s
navigation URL
serialized
The
tag
getter steps are to return
this
’s
notification
’s
tag
The
image
getter steps are:
If there is no
this
’s
notification
’s
image URL
, then
return the empty string.
Return
this
’s
notification
’s
image URL
serialized
The
icon
getter steps are:
If there is no
this
’s
notification
’s
icon URL
, then
return the empty string.
Return
this
’s
notification
’s
icon URL
serialized
The
badge
getter steps are:
If there is no
this
’s
notification
’s
badge URL
, then
return the empty string.
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:
Let
frozenActions
be an empty list of type
NotificationAction
For each
entry
of
this
’s
notification
’s
actions
Let
action
be a new
NotificationAction
Set
action
["
action
"] to
entry
’s
name
Set
action
["
title
"] to
entry
’s
title
If
entry
’s
navigation URL
is non-null, then
set
action
["
navigate
"] to
entry
’s
navigation URL
serialized
If
entry
’s
icon URL
is non-null, then set
action
["
icon
"] to
entry
’s
icon URL
serialized
Call
Object.freeze
on
action
, to
prevent accidental mutation by scripts.
Append
action
to
frozenActions
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
};
service worker registration
has an associated
has
showNotification()
been successfully invoked
(a
boolean
), which is initially false.
This is infrastructure for the
Push API
standard.
[PUSH-API]
The
showNotification(
title
options
method steps are:
Let
global
be
this
’s
relevant global object
Let
promise
be
a new promise
in
this
’s
relevant Realm
If
this
’s
active worker
is null, then
reject
promise
with a
TypeError
and return
promise
Let
notification
be the result of
creating a notification with a settings object
given
title
options
and
this
’s
relevant settings object
. If this threw an exception, then
reject
promise
with that exception and return
promise
Set
notification
’s
service worker registration
to
this
Run these steps
in parallel
If the result of
getting the notifications permission state
is not
granted
", then
queue a global task
on the
DOM manipulation task source
given
global
to
reject
promise
with a
TypeError
, and abort these steps.
Run the
notification show steps
for
notification
Set
notification
’s
service worker registration
’s
has
showNotification()
been successfully invoked
to true.
Queue a global task
on the
DOM manipulation task source
given
global
to
resolve
promise
with undefined.
Return
promise
The
getNotifications(
filter
method steps are:
Let
global
be
this
’s
relevant global object
Let
realm
be
this
’s
relevant Realm
Let
origin
be
this
’s
relevant settings object
’s
origin
Let
promise
be
a new promise
in
realm
Run these steps
in parallel
Let
tag
be
filter
["
tag
"].
Let
notifications
be a
list
of all
notifications
in the
list of notifications
whose
origin
is
same origin
with
origin
, whose
service worker registration
is
this
, and
whose
tag
, if
tag
is not the empty string, is
tag
Queue a global task
on the
DOM manipulation task source
given
global
to run these steps:
Let
objects
be a
list
For each
notification
in
notifications
, in creation
order, create a
new
Notification
object with
realm
representing
notification
, and
append
it to
objects
Resolve
promise
with
objects
Return
promise
This method returns zero or more new
Notification
objects which might represent
the same underlying
notification
of
Notification
objects already in existence.
To
fire a service worker notification event
named
name
given a
notification
notification
, and an optional string
action
(default
the empty string): run
Fire Functional Event
given
name
NotificationEvent
notification
’s
service worker registration
, and the following
initialization:
notification
A new
Notification
object representing
notification
action
action
The
notification
getter steps are to
return the value it was initialized to.
The
action
getter steps are to return the
value it was initialized to.
The following is the
event handler
(and its corresponding
event handler event type
) that must be supported as attribute by the
ServiceWorkerGlobalScope
object:
event handler
event handler event type
onnotificationclick
notificationclick
onnotificationclose
notificationclose
Acknowledgments
Thanks to
Addison Phillips,
Aharon (Vladimir) Lanin,
Alex Russell,
Anssi Kostiainen,
Arkadiusz Michalski,
Boris Zbarsky,
Brady Eidson,
David Håsäther,
Doug Turner,
Drew Wilson,
Ehsan Akhgari,
Frederick Hirsch,
Ian Hickson,
Jake Archibald,
James Graham,
John Mellor,
Jon Lee,
Jonas Sicking,
Kagami Sascha Rosylight,
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
annevk@annevk.nl
). An
earlier iteration was written by John Gregg (
Google
johnnyg@google.com
).
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
Index
Terms defined by this specification
action
attribute for NotificationEvent
, in § 4
dict-member for NotificationAction
, in § 3
dict-member for NotificationEventInit
, in § 4
actions
attribute for Notification
, in § 3.4
dfn for notification
, in § 2
dict-member for NotificationOptions
, in § 3
alert steps
, in § 2.9
"auto"
, in § 3
badge
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
badge resource
, in § 2
badge URL
, in § 2
body
attribute for Notification
, in § 3.4
dfn for notification
, in § 2
dict-member for NotificationOptions
, in § 3
close()
, in § 3.4
close steps
, in § 2.8
constructor(title)
, in § 3.2
constructor(title, options)
, in § 3.2
constructor(type, eventInitDict)
, in § 4
create a notification
, in § 2
create a notification with a settings object
, in § 2
data
attribute for Notification
, in § 3.4
dfn for notification
, in § 2
dict-member for NotificationOptions
, in § 3
"default"
, in § 3
"denied"
, in § 3
dir
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
direction
, in § 2
fetch steps
, in § 2.5
fire a service worker notification event
, in § 4
GetNotificationOptions
, in § 4
getNotifications()
, in § 4
getNotifications(filter)
, in § 4
get the notifications permission state
, in § 2.2
"granted"
, in § 3
handle close events
, in § 2.8
has showNotification() been successfully invoked
, in § 4
icon
attribute for Notification
, in § 3.4
dict-member for NotificationAction
, in § 3
dict-member for NotificationOptions
, in § 3
icon resource
dfn for notification
, in § 2
dfn for notification action
, in § 2
icon URL
dfn for notification
, in § 2
dfn for notification action
, in § 2
image
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
image resource
, in § 2
image URL
, in § 2
lang
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
language
, in § 2
list of notifications
, in § 2.1
"ltr"
, in § 3
maxActions
, in § 3.3
maximum number of actions
, in § 2
name
, in § 2
navigate
attribute for Notification
, in § 3.4
dict-member for NotificationAction
, in § 3
dict-member for NotificationOptions
, in § 3
navigation URL
dfn for notification
, in § 2
dfn for notification action
, in § 2
non-persistent notification
, in § 2
Notification
, in § 3
notification
attribute for NotificationEvent
, in § 4
definition of
, in § 2
dict-member for NotificationEventInit
, in § 4
notification action
, in § 2
NotificationAction
, in § 3
NotificationDirection
, in § 3
NotificationEvent
, in § 4
NotificationEventInit
, in § 4
NotificationEvent(type, eventInitDict)
, in § 4
NotificationOptions
, in § 3
NotificationPermission
, in § 3
NotificationPermissionCallback
, in § 3
notifications
, in § 2.2
notification show steps
, in § 2.6
Notification(title)
, in § 3.2
Notification(title, options)
, in § 3.2
onclick
, in § 3.4
onclose
, in § 3.4
onerror
, in § 3.4
onnotificationclick
, in § 4
onnotificationclose
, in § 4
onshow
, in § 3.4
origin
, in § 2
permission
, in § 3.3
persistent notification
, in § 2
renotify
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
renotify preference
, in § 2
requestPermission()
, in § 3.3
requestPermission(deprecatedCallback)
, in § 3.3
requireInteraction
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
require interaction preference
, in § 2
"rtl"
, in § 3
service worker registration
, in § 2
showNotification(title)
, in § 4
showNotification(title, options)
, in § 4
silent
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
silent preference
, in § 2
tag
attribute for Notification
, in § 3.4
dfn for notification
, in § 2
dict-member for GetNotificationOptions
, in § 4
dict-member for NotificationOptions
, in § 3
timestamp
attribute for Notification
, in § 3.4
dfn for notification
, in § 2
dict-member for NotificationOptions
, in § 3
title
attribute for Notification
, in § 3.4
dfn for notification
, in § 2
dfn for notification action
, in § 2
dict-member for NotificationAction
, in § 3
vibrate
attribute for Notification
, in § 3.4
dict-member for NotificationOptions
, in § 3
vibration pattern
, in § 2
Terms defined by reference
[]
defines the following terms:
VibratePattern
freeze
perform vibration
Record
validate and normalize
[DOM]
defines the following terms:
EventTarget
cancelable
event listener
fire an event
[FETCH]
defines the following terms:
fetch
internal response
response
type
[HR-TIME]
defines the following terms:
EpochTimeStamp
current wall time
unix epoch
[HTML]
defines the following terms:
EventHandler
StructuredDeserialize
StructuredSerializeForStorage
API base URL
browsing context
create a fresh top-level traversable
current global object
DOM manipulation task source
environment settings object
event handler
event handler event type
focus()
in parallel
navigate
origin
origin
(for environment settings object)
queue a global task
queue a task
relevant global object
relevant realm
relevant settings object
same origin
top-level traversable
top-level traversable set
[INFRA]
defines the following terms:
append
boolean
contain
empty
exist
for each
implementation-defined
list
remove
replace
[Permissions]
defines the following terms:
getting the current permission state
name
powerful feature
query()
requesting permission to use
[SERVICE-WORKERS]
defines the following terms:
ExtendableEvent
ExtendableEventInit
ServiceWorkerGlobalScope
ServiceWorkerRegistration
active worker
Fire Functional Event
service worker registration
[URL]
defines the following terms:
URL
URL parser
URL serializer
[WEBIDL]
defines the following terms:
DOMString
Exposed
FrozenArray
Promise
SameObject
TypeError
USVString
a new promise
any
boolean
create a frozen array
dictionary
invoke
new
reject
resolve
sequence
this
throw
undefined
unsigned long
References
Normative References
[BCP47]
A. Phillips, Ed.; M. Davis, Ed..
Tags for Identifying Languages
. September 2009. Best Current Practice. URL:
[BIDI]
Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy.
Unicode Bidirectional Algorithm
. 13 August 2025. Unicode Standard Annex #9. URL:
[DOM]
Anne van Kesteren.
DOM Standard
. Living Standard. URL:
[FETCH]
Anne van Kesteren.
Fetch Standard
. Living Standard. URL:
[HR-TIME]
Yoav Weiss.
High Resolution Time
. URL:
[HTML]
Anne van Kesteren; et al.
HTML Standard
. Living Standard. URL:
[INFRA]
Anne van Kesteren; Domenic Denicola.
Infra Standard
. Living Standard. URL:
[Permissions]
Marcos Caceres; Mike Taylor.
Permissions
. URL:
[SERVICE-WORKERS]
Monica CHINTALA; Yoshisato Yanagisawa.
Service Workers Nightly
. URL:
[URL]
Anne van Kesteren.
URL Standard
. Living Standard. URL:
[VIBRATION]
Anssi Kostiainen.
Vibration API
. URL:
[WEBIDL]
Edgar Chen; Timothy Gu.
Web IDL Standard
. Living Standard. URL:
Informative References
[PUSH-API]
Marcos Caceres; Kagami Rosylight.
Push API
. URL:
IDL Index
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
USVString
navigate
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
= "";
USVString
navigate
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
navigate
USVString
icon
};
callback
NotificationPermissionCallback
undefined
NotificationPermission
permission
);
dictionary
GetNotificationOptions
DOMString
tag
= "";
};
partial
interface
ServiceWorkerRegistration
Promise
undefined
showNotification
DOMString
title
optional
NotificationOptions
options
= {});
Promise
sequence
Notification
>>
getNotifications
optional
GetNotificationOptions
filter
= {});
};