postMessage API

HTML5 postMessage API Overview

The HTML5 postMessage() API allows safe communication between different browsing contexts such as windows, tabs, popups, iframes, and embedded applications. It is especially useful when two pages are from different origins and cannot directly access each other because of the browser's same-origin policy.

The postMessage API is commonly used for iframe communication, embedded widgets, payment flows, authentication popups, micro frontends, browser extensions, analytics embeds, chat widgets, and cross-domain integrations.

Basic postMessage Example

// Send message to another window

const iframe =
  document.querySelector("#paymentFrame");

iframe.contentWindow.postMessage(
  "Hello iframe",
  "https://payments.example.com"
);

// Receive message

window.addEventListener("message", (event) => {
  if (event.origin !== "https://payments.example.com") {
    return;
  }

  console.log("Message received:", event.data);
});

This example sends a message to an iframe and receives a response using the message event. The receiver checks event.origin before trusting the message.

How postMessage Works

postMessage Syntax

targetWindow.postMessage(
  message,
  targetOrigin
);

MessageEvent Properties

Parent Page to iframe Example

<iframe
  id="profileFrame"
  src="https://widgets.example.com/profile">
</iframe>

<script>
const frame =
  document.querySelector("#profileFrame");

frame.addEventListener("load", () => {
  frame.contentWindow.postMessage(
    {
      type: "USER_DATA",
      userId: 101
    },
    "https://widgets.example.com"
  );
});
</script>

The parent page sends structured data to an embedded iframe after the iframe loads.

iframe to Parent Page Example

// Inside iframe page

window.parent.postMessage(
  {
    type: "PROFILE_READY",
    height: document.body.scrollHeight
  },
  "https://app.example.com"
);

This pattern is commonly used by embedded widgets to notify the parent page when content is ready or when the iframe height changes.

Receive Structured Messages

const allowedOrigin =
  "https://widgets.example.com";

window.addEventListener("message", (event) => {
  if (event.origin !== allowedOrigin) {
    return;
  }

  const message =
    event.data;

  if (!message || message.type !== "PROFILE_READY") {
    return;
  }

  console.log(
    "Widget height:",
    message.height
  );
});

Structured messages with a type field are easier to validate, route, and maintain than plain string messages.

Popup Authentication Example

// Parent window

const popup =
  window.open(
    "https://auth.example.com/login",
    "authPopup",
    "width=500,height=600"
  );

window.addEventListener("message", (event) => {
  if (event.origin !== "https://auth.example.com") {
    return;
  }

  if (event.data.type === "AUTH_SUCCESS") {
    console.log(
      "Token:",
      event.data.token
    );

    popup.close();
  }
});

// Popup window

window.opener.postMessage(
  {
    type: "AUTH_SUCCESS",
    token: "temporary-token"
  },
  "https://app.example.com"
);

Authentication popups often use postMessage() to send a result back to the original application window.

Reply to a Message

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.example.com") {
    return;
  }

  if (event.data.type === "PING") {
    event.source.postMessage(
      {
        type: "PONG"
      },
      event.origin
    );
  }
});

The event.source property provides a reference to the sender, allowing the receiver to respond directly.

Transfer ArrayBuffer Example

const buffer =
  new ArrayBuffer(1024);

iframe.contentWindow.postMessage(
  {
    type: "BINARY_DATA",
    buffer: buffer
  },
  "https://processor.example.com",
  [buffer]
);

Transferable objects move ownership instead of copying data. This is more efficient for large binary data but means the original context can no longer use the transferred object.

MessageChannel with postMessage

const channel =
  new MessageChannel();

iframe.contentWindow.postMessage(
  {
    type: "CONNECT"
  },
  "https://widgets.example.com",
  [channel.port2]
);

channel.port1.onmessage = (event) => {
  console.log(
    "Channel message:",
    event.data
  );
};

channel.port1.postMessage(
  {
    type: "HELLO"
  }
);

MessageChannel creates a dedicated communication channel between contexts and is useful for more complex integrations.

postMessage Security Rules

Safe Message Contract Example

const message =
  {
    type: "CART_UPDATED",
    version: 1,
    payload: {
      cartId: "cart-123",
      itemCount: 3
    }
  }

iframe.contentWindow.postMessage(
  message,
  "https://checkout.example.com"
);

A consistent message contract makes cross-window communication easier to validate, document, test, and maintain.

Common postMessage API Use Cases

• Parent page and iframe communication.
• Payment iframe checkout integrations.
• Authentication popup callbacks.
• Embedded chat widgets.
• Micro frontend communication.
• Browser extension content scripts.
• Cross-domain analytics widgets.
• Resizing embedded iframe content.

postMessage API Best Practices

• Always specify an exact targetOrigin.
• Always validate event.origin before reading data.
• Use structured messages with a clear type.
• Validate message shape before acting on it.
• Avoid sending passwords, long-lived tokens, or sensitive user data.
• Remove message listeners when they are no longer needed.
• Use allowlists when communicating with multiple trusted origins.
• Document your message contract for long-term maintainability.

Common postMessage Mistakes

• Using "*" as targetOrigin for sensitive messages.
• Not checking event.origin.
• Trusting event.data without validation.
• Sending secrets or long-lived tokens through messages.
• Forgetting that any window can send a message event.
• Not removing temporary message listeners.
• Using inconsistent message formats across teams.
• Assuming iframe content is ready before sending messages.

postMessage vs Broadcast Channel vs Web Workers

Key Takeaways

• The postMessage API enables communication between windows, iframes, popups, and workers.
• Use targetWindow.postMessage(message, targetOrigin) to send messages.
• Use the message event to receive messages.
• Always validate event.origin before trusting a message.
• Use exact origins instead of "*" for sensitive data.
• Use structured message contracts for reliable integrations.