Worker: postMessage() method
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Note: This feature is available in Web Workers, except for Service Workers.
The postMessage() method of the Worker interface sends a message to the worker. The first parameter is the data to send to the worker. The data may be any JavaScript object that can be handled by the structured clone algorithm.
The Worker postMessage() method delegates to the MessagePort postMessage() method, which adds a task on the event loop corresponding to the receiving MessagePort.
The Worker can send back information to the thread that spawned it using the DedicatedWorkerGlobalScope.postMessage method.
Syntax
postMessage(message)
postMessage(message, transfer)
postMessage(message, options)
Parameters
message-
The object to deliver to the worker; this will be in the
datafield in the event delivered to themessageevent. This may be any value or JavaScript object handled by the structured clone algorithm, which includes cyclical references.The
messageparameter is mandatory. If the data to be passed to the worker is unimportant,nullorundefinedmust be passed explicitly. transferOptional-
An optional array of transferable objects to transfer ownership of. The ownership of these objects is given to the destination side and they are no longer usable on the sending side. These transferable objects are not automatically sent; they must either be contained in the message or be accessible to the recipient via other means, such as
MessagePortviaMessageEvent.ports. optionsOptional-
An optional object containing the following properties:
transferOptional-
Has the same meaning as the
transferparameter.
Return value
None (undefined).
Examples
The following code snippet shows the creation of a Worker object using the Worker() constructor. When either of two form inputs (first and second) have their values changed, change events invoke postMessage() to send the value of both inputs to the current worker.
const myWorker = new Worker("worker.js");
[first, second].forEach((input) => {
input.onchange = () => {
myWorker.postMessage([first.value, second.value]);
console.log("Message posted to worker");
};
});
For a full example, see our simple worker example (run example).
Note:
postMessage() can only send a single object at once. As seen above, if you want to pass multiple values you can send an array.
Transfer Example
This minimum example has main create an ArrayBuffer and transfer it to myWorker, then has myWorker transfer it back to main, with the size logged at each step.
main.js code
// create worker
const myWorker = new Worker("myWorker.js");
// listen for myWorker to transfer the buffer back to main
myWorker.addEventListener("message", (msg) => {
console.log("message from worker received in main:", msg);
const bufTransferredBackFromWorker = msg.data;
console.log(
"buf.byteLength in main AFTER transfer back from worker:",
bufTransferredBackFromWorker.byteLength,
);
});
// create the buffer
const myBuf = new ArrayBuffer(8);
console.log(
"buf.byteLength in main BEFORE transfer to worker:",
myBuf.byteLength,
);
// send myBuf to myWorker and transfer the underlying ArrayBuffer
myWorker.postMessage(myBuf, [myBuf]);
console.log(
"buf.byteLength in main AFTER transfer to worker:",
myBuf.byteLength,
);
myWorker.js code
// listen for main to transfer the buffer to myWorker
self.onmessage = (msg) => {
console.log("message from main received in worker:", msg);
const bufTransferredFromMain = msg.data;
console.log(
"buf.byteLength in worker BEFORE transfer back to main:",
bufTransferredFromMain.byteLength,
);
// send buf back to main and transfer the underlying ArrayBuffer
self.postMessage(bufTransferredFromMain, [bufTransferredFromMain]);
console.log(
"buf.byteLength in worker AFTER transfer back to main:",
bufTransferredFromMain.byteLength,
);
};
Output logged
buf.byteLength in main BEFORE transfer to worker: 8 main.js:19
buf.byteLength in main AFTER transfer to worker: 0 main.js:27
message from main received in worker: MessageEvent { ... } myWorker.js:3
buf.byteLength in worker BEFORE transfer back to main: 8 myWorker.js:7
buf.byteLength in worker AFTER transfer back to main: 0 myWorker.js:15
message from worker received in main: MessageEvent { ... } main.js:6
buf.byteLength in main AFTER transfer back from worker: 8 main.js:10
byteLength goes to 0 after the ArrayBuffer is transferred. For a more sophisticated full working example of ArrayBuffer transfer, see this Firefox demo add-on: GitHub :: ChromeWorker - demo-transfer-arraybuffer
Specifications
| Specification |
|---|
| HTML # dom-worker-postmessage-dev |
Browser compatibility
| desktop | mobile | server | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
postMessage
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
options.includeUserActivation parameter
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Non-standard. Check cross-browser support before using.
- See implementation notes.
- Has more compatibility info.
See also
- The
Workerinterface it belongs to.