ServiceWorker: postMessage() method
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The postMessage()
method of the ServiceWorker
interface sends a message to the worker. This accepts a single parameter, which is the data to send to the worker. The data may be any JavaScript object which can be handled by the structured clone algorithm.
The service worker can send back information to its clients by using the postMessage()
method. The message will not be sent back to this ServiceWorker
object but to the associated ServiceWorkerContainer
available via navigator.serviceWorker
.
Syntax
js
postMessage(message)
postMessage(message, options)
postMessage(message, transfer)
Parameters
message
-
The object to deliver to the worker; this will be in the
data
field in the event delivered to themessage
event. This may be any JavaScript object handled by the structured clone algorithm.The
message
parameter is mandatory. If the data to be passed to the worker is unimportant,null
orundefined
must be passed explicitly. options
Optional-
An optional object containing a
transfer
field with an array of transferable objects to transfer ownership of. transfer
Optional-
An optional array of transferable objects to transfer ownership of. If the ownership of an object is transferred, it becomes unusable in the context it was sent from and becomes available only to the worker it was sent to.
Transferable objects are instances of classes like
ArrayBuffer
,MessagePort
orImageBitmap
objects that can be transferred.null
is not an acceptable value fortransfer
.
Note: The parameters options
and transfer
can't both be used at the same time.
Return value
None (undefined
).
Exceptions
SyntaxError
-
Thrown if the
message
parameter is not provided.
Examples
In this example a ServiceWorker
is created and a message is immediately sent:
js
navigator.serviceWorker.register("service-worker.js");
navigator.serviceWorker.ready.then((registration) => {
registration.active.postMessage(
"Test message sent immediately after creation"
);
});
In order to receive the message, the service worker, in service-worker.js
has to listen to the message
event on its global scope.
js
// This must be in `service-worker.js`
addEventListener("message", (event) => {
console.log(`Message received: ${event.data}`);
});
Note that the service worker can send back messages to the main thread using the postMessage()
method. To receive it, the main thread needs to listen for a message
event on the ServiceWorkerContainer
object.
Specifications
Specification |
---|
Service Workers # dom-serviceworker-postmessage |
Service Workers # dom-serviceworker-postmessage-message-options |
Browser compatibility
BCD tables only load in the browser
See also
- The
ServiceWorker
interface it belongs to. - Its counterpart, the
postMessage()
method that a service worker must use to send a message back to the associatedServiceWorkerContainer
.