Reference

postMessage rules

Short rules. Words match CONTEXT.md.

Lesson 1 Lesson 2 Lesson 3 Lesson 4 Lesson 5 Lesson 6 Lesson 7 Lesson 8 Glossary Words Resources

How you get a handle

You want	You write
Window inside an iframe element	`iframe.contentWindow`
Page that embeds this page	`window.parent`
Outermost page	`window.top`
Page that opened this popup	`window.opener`
New window you just opened	the return value of `window.open`

If you are not in an iframe, parent and top are this window. A popup is not in an iframe. On a popup, parent is the popup. noopener means open returns null.

What you hold

You write	You hold	Same origin	Different origin
`iframe.contentWindow`	WindowProxy of the child	You can read the document	You can use postMessage
`window.parent` / `top`	WindowProxy of the parent	You can read the document	You can use postMessage
`window.open` / `opener`	WindowProxy of the popup	You can read the document	You can use postMessage

If the origins are different, you can use postMessage, focus, blur, and close. You can read closed, frames, opener, parent, top. MDN.

Two fields

targetOrigin

You set this when you send. The receiver origin must match. If it does not match, the browser discards the data. There is no error. "/" means your origin. "*" means any origin.

event.origin

You read this when you receive. It is the origin of the sender. If you do not check it, any holder of your WindowProxy can send data to you.

event.source

You read this when you receive. It is the WindowProxy of the sender. Reply on it. Pass event.origin as targetOrigin. Compare it to iframe.contentWindow to find the element.

What the browser does

The browser makes a structured clone of the data. A bad value throws now.
If targetOrigin is not * and the receiver origin does not match, the browser returns. There is no event.
The browser queues a task. Your current code finishes first.
The browser fires message with data, origin, and source.

Source: HTML — window post message steps.

Defaults

If you are in the same window, call a function. Do not use postMessage.
Set a real targetOrigin. Do not use "*" with secrets.
First line of the listener: if (event.origin !== EXPECTED) return;
To reply: event.source.postMessage(reply, event.origin).
Wait until the child sends ready. Do not send data to a new iframe at once. load is not ready. A reload clears ready.

Who can hear

Same page — call a function.
Many same-origin tabs — BroadcastChannel.
One widget, a few messages — window postMessage. Check event.origin.
Other widgets must not hear — transfer a port after ready.
The first port still travels on the window.
Close the port when you are done. Lesson 7.
Check event.origin, then the shape of event.data. Do not treat it as the server.

Not this API

BroadcastChannel — same origin only. No targetOrigin.
Worker.postMessage — one page and its worker. See the Web Workers topic.
MessageChannel — keep port1, transfer port2 after ready. The port has no targetOrigin. Lesson 5.