JavaScript Worker postMessage() Method

What You’ll Learn

The postMessage() method of Worker sends a message to the worker. Data is copied with the structured clone algorithm (or ownership can be transferred for buffers). Learn one-payload messages, arrays of values, replies via onmessage, and ArrayBuffer transfer—with five examples and try-it labs.

Introduction

After you create a worker with new Worker(), you talk to it with messages. From the main thread call worker.postMessage(data). Inside the worker, listen with self.onmessage (or addEventListener("message")) and read event.data.

The worker answers with self.postMessage(...). That is a different method on the worker global scope, but the idea is the same: clone (or transfer) data across the thread boundary.

Understanding Worker.postMessage()

An instance method that queues a message for the worker. The first argument is mandatory and becomes event.data in the worker’s message event.

• message — any structured-cloneable value (required; use null / undefined if empty).
• transfer — optional array of transferable objects to move (not copy).
• options.transfer — same meaning in the object form of the call.
• Return value — none (undefined).
• Baseline Widely available on MDN (since July 2015); available in Web Workers except Service Workers.

📝 Syntax

postMessage(message)
postMessage(message, transfer)
postMessage(message, options)

Parameters

Return value

None (undefined).

Typical pattern

const worker = new Worker("worker.js");

worker.onmessage = (event) => {
  console.log("from worker:", event.data);
};

worker.postMessage([first.value, second.value]);

⚖️ postMessage() vs Related Ideas

Examples Gallery

Examples follow MDN Worker: postMessage(). Labs use blob workers so they run in one HTML file.

worker.onmessage = (e) => console.log(e.data);
worker.postMessage("hello");
// worker: self.onmessage = (e) => self.postMessage("echo: " + e.data);

echo: hello

worker.postMessage([first.value, second.value]);
// worker: const [a, b] = e.data; self.postMessage(Number(a) + Number(b));

sum = 5

worker.postMessage({ user: "Ada", scores: [10, 20] });
// worker returns: e.data.user + " total=" + sum(e.data.scores)

Ada total=30

const buf = new ArrayBuffer(8);
console.log(buf.byteLength); // 8
worker.postMessage(buf, [buf]);
console.log(buf.byteLength); // 0 — ownership moved
// worker can transfer it back the same way

before: 8
after send: 0
worker saw: 8

worker.postMessage(null); // not worker.postMessage()
// worker: self.postMessage("pong");

pong

🚀 Common Use Cases

• Send form values or job parameters to a background worker.
• Ship large typed arrays / images with transfer for performance.
• Request/response protocols (id + payload in one object).
• Ping a worker to confirm it is alive (postMessage(null)).
• Teaching structured clone vs shared memory / transfer.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• Available in Web Workers except Service Workers.
• Message argument is mandatory.
• Functions and DOM nodes are not structured-cloneable.
• Related learning: Worker(), addEventListener(), JavaScript hub.

💡 Best Practices