How to Send Data Between Wix Studio and HTML Embed Using postMessage
- Aug 5
- 7 min read
An HTML Embed is one of the easiest ways to add custom HTML, CSS, JavaScript, or a third-party widget to a Wix Studio website.
However, an HTML Embed runs inside a sandboxed iframe. It cannot directly read or modify the other Wix elements on the page.
To exchange information between the iframe and your Wix Studio page, you need to use two APIs:
postMessage() to send data
onMessage() to receive data
In this practical guide, we will build a working two-way price calculator and explain how Wix Studio HTML Embed postMessage communication works in both directions.
The completed example will allow the Wix Studio page to send the currency, price, quantity, and discount to the HTML Embed. The embedded calculator will process the values and send the calculated result back to the Wix page.
An HTML iframe element is isolated from the rest of the Wix page, but Wix supports exchanging JavaScript data between page code and the component through its messaging APIs.
How Wix Studio HTML Embed postMessage Communication Works
Communication takes place in two directions.
From the Wix Studio page to the HTML Embed
From the HTML Embed to the Wix Studio page
The page sends data to the HTML component with its $w API. Inside the iframe, the data is available through the browser’s message event.
For the return direction, the iframe posts a message to its parent window, and the Wix page receives it through the HTML component’s onMessage() handler.
What We Are Building
Our example contains:
an HTML Embed with a price calculator;
a Wix text element showing the final result;
a Wix button that sends updated values to the calculator;
two-way communication between Wix Studio and the iframe;
a ready-state handshake to prevent messages from being sent too early;
message validation based on a type property.
Wix Studio page elements
Add the following elements to the page:
Element | ID | Purpose |
HTML Embed | Displays the calculator | |
Text | Displays the returned total | |
Button | Sends new configuration | |
Text | Displays connection status |
The HTML Embed should be approximately 100% wide and at least 500px high.
Why You Should Not Send Data Immediately in $w.onReady()
A common implementation looks like this:
$w.onReady(() => {
$w("#priceCalculator").postMessage(
{type: "SET_CONFIG",price: 50
});
});This is unreliable.
The Wix page may finish loading before the HTML iframe is ready to receive messages. Wix explicitly notes that an HTML Component often loads shortly after its parent page, meaning a call from $w.onReady() can happen too early.
The better approach is a handshake:
This ensures that the HTML component is listening before the page sends its first message.
Step 1: Add the HTML Embed Code
Open the HTML Embed element and paste the following complete code.
Replace:
with the exact published origin of your website.
Do not add a trailing slash.
Step 2: Add the Wix Studio Page Code
Add the following code to the page containing the HTML Embed.
How the Wix Studio Page Sends Data to the HTML Embed
This part sends a structured JavaScript object from the Wix Studio page to the HTML Embed using the component’s postMessage() method.
The HTML component receives the message through the browser’s message event.
Wix allows messages to contain valid JavaScript data, including strings, numbers, arrays, and objects. For most integrations, an object containing type and payload is cleaner than sending several unrelated values.
How the HTML Embed Sends Data Back to Wix Studio
Inside the iframe, the calculator sends its calculation result to the parent Wix Studio page using window.parent.postMessage().
The Wix Studio page receives this data through the HTML component’s onMessage() event handler.
The received message is available through event.data.
Why Every Message Has a Type
Avoid sending ambiguous raw values such as a number with no context:
A larger HTML component may eventually send:
initialization events;
calculation results;
validation errors;
resize requests;
form submissions;
analytics events.
A typed message creates a clear and predictable messaging protocol:
The receiver can then route each message according to its type:
This is much easier to maintain than trying to infer what an isolated string or number represents.
Secure targetOrigin in Wix HTML Embed
You will often see code that sends messages using "*":
This works, but it should not be the default production implementation.
Using "*" does not restrict message delivery to a known recipient. For a published Wix Studio website, specify the site origin explicitly:
The origin must contain only:
protocol + domain + optional port
Correct:
Incorrect:
Preview Mode Warning
Your published website and Wix Preview do not necessarily use the same origin.
For the final production implementation, use the published site origin. During development, logging event.origin can help you identify the parent origin used in Preview.
Do not permanently weaken production message validation only to make Preview testing easier.
Validate Incoming Messages
A message event should not automatically be trusted.
At minimum, verify:
the sender origin;
that event.data is an object;
that the message has a known type;
that required payload values use the expected data types.
Inside the HTML Embed:
On the Wix Studio page:
This does not replace backend validation for sensitive operations, but it prevents malformed component messages from breaking the interface.
Do Not Put Sensitive Business Logic in the HTML Embed
The HTML Embed runs in the visitor’s browser.
That means users can inspect:
HTML;
JavaScript;
API URLs;
calculation rules;
embedded credentials;
client-side validation.
Never place a secret API key inside iframe code:
You should also never trust a payment amount returned by an HTML calculator. A visitor can manipulate any client-side message before it reaches your Wix page.
For sensitive operations, send the required input to a backend web method and calculate or validate the authoritative result there.
The correct architecture is:
HTML Embed sends input to the Wix page.
The Wix page calls a backend web method.
The backend validates the data or contacts an external API.
The verified result returns to the Wix page.
The Wix page updates the HTML Embed.
Sensitive calculations, permissions, payments, subscription status, and private API requests must not rely exclusively on iframe code.
Common Wix Studio HTML Embed postMessage Errors
1. The First Message Is Never Received
Cause: The page calls postMessage() before the iframe has finished loading.
Fix: Use the HTML_COMPONENT_READY handshake.
2. onMessage() Never Runs
Check that:
the correct HTML component ID is used;
the handler is registered inside $w.onReady();
the iframe uses window.parent.postMessage();
targetOrigin matches the published site origin;
the HTML component has fully loaded.
3. Messages Work in Preview but Fail After Publishing
This usually means the production origin differs from the value used during development.
Verify:
const SITE_ORIGIN = "https://www.yourdomain.com";
The value must match the live domain exactly.
4. Messages Work on the Live Site but Not in Preview
Wix Preview can use a different parent origin.
Do not replace your live origin with "*" and publish that as the final solution. Test the production messaging flow on the published website.
5. The Message Is Received, but the UI Does Not Update
Check the object structure on both sides.
Sender:
message.payload.price
Not:
message.price
Both sides must use the same message contract.
6. The Calculator Returns NaN
Values returned by HTML input fields are strings. Convert them before performing calculations:
const price = Number(elements.price.value);
Then validate the result:
const safePrice = Number.isFinite(price) ? price : 0;
7. The Wix Page Trusts a Manipulated Total
Anything calculated in the browser can be modified by the visitor.
Treat client-side totals as display values only. Recalculate important totals in backend code before creating an order, payment, booking, subscription, or database record.
When Should You Use This Architecture?
A Wix HTML Embed with postMessage() is useful for:
interactive calculators;
charts and data visualizations;
signature pads;
external JavaScript widgets;
custom code editors;
map interfaces;
iframe-based booking tools;
embedded forms;
legacy frontend applications.
An HTML Embed is especially useful when the custom interface can remain mostly isolated while exchanging a limited amount of structured data with the Wix page.
When a component requires frequent native page interaction, reusable methods or properties, or tighter integration with Velo, a Custom Element may provide a cleaner architecture.
Final Thoughts
The most reliable way to connect a Wix Studio page with an HTML Embed is to treat the iframe as a separate application with a small and predictable messaging contract.
The essential flow is:
The HTML component sends HTML_COMPONENT_READY.
The Wix page sends the initial configuration.
The HTML component processes the user’s input.
The HTML component sends a typed result.
The Wix page validates and handles the result.
Using postMessage(), onMessage(), a ready-state handshake, typed payloads, and strict validation makes the integration easier to debug and safer to maintain.
For visual widgets and isolated JavaScript tools, this architecture works well. For sensitive business logic, database permissions, payments, or private API requests, the final validation must remain in Wix backend code.
FAQ
How Do I Send Data to an HTML Embed in Wix Studio?
Use the HTML component’s postMessage() method in the Wix page code:
$w("#priceCalculator").postMessage(...)
How Do I Send Data from HTML Embed to Wix Studio?
Use window.parent.postMessage() inside the HTML component. Then receive the message with the HTML component’s onMessage() handler in Wix page code.
Why Does postMessage() Not Work Immediately Inside $w.onReady()?
The Wix page may become ready before the embedded iframe has finished loading. The initial message can be sent before the iframe registers its event listener.
Use a ready-state handshake and send the initial configuration only after receiving HTML_COMPONENT_READY.
Can an HTML Embed Access Other Wix Studio Elements?
No. The HTML element runs inside a sandboxed iframe and does not have direct access to the other elements on the Wix page. Communication must happen through messages.
Can I Send an Object Through postMessage()?
Yes. Structured objects containing type and payload are usually the easiest format to validate and maintain.
Is window.parent.postMessage() with "*" Safe?
It is less restrictive because it does not limit the recipient to a specific origin. For production, specify the exact site origin.
Can I Store an API Key Inside the HTML Embed?
No. HTML and JavaScript inside the iframe execute in the visitor’s browser and can be inspected. Use Wix backend code and Secrets Manager for private integrations.
