How to Embed a Widget in Appsmith
Appsmith is an open-source platform for building internal tools. Its Iframe widget supports both URL and srcDoc modes, making it straightforward to embed your Embeddy widget on any page of your Appsmith application — with optional dynamic bindings from queries and APIs.
On this page
Prerequisites
Before embedding, make sure you have the following ready:
- An Embeddy widget: Create one for free at embeddy.ai/dashboard. Your widget must be published so it is publicly accessible.
- Your Embed Link or iframe code: Copy the Embed Link URL for the URL method, or the full iframe code for the srcDoc method.
- An Appsmith account: Cloud (app.appsmith.com) or self-hosted. The Iframe widget is available on all editions.
URL vs srcDoc: The URL mode loads external content by URL (simplest). The srcDoc mode lets you paste raw HTML into the iframe (useful for custom iframe attributes). Both work with Embeddy widgets.
Method 1: Iframe Widget (URL Mode)
Recommended — simplest approach
- 1
Open your Appsmith app in the editor
Navigate to the page where you want to add the widget.
- 2
Drag an Iframe widget onto the canvas
In the widget panel on the left, search for "Iframe" and drag it onto your canvas. Resize it to fit your layout.
- 3
Set the URL property
In the property pane on the right, set the URL property to your Embeddy Embed Link:
https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID
- 4
Deploy and test
Click Deploy to publish your changes, then open the deployed app to verify the widget renders correctly.
Tip: The widget should render live in the editor as well. If it does not, click outside the Iframe widget and back — Appsmith sometimes needs a click to trigger the iframe load.
Method 2: Iframe Widget (srcDoc Mode)
Alternative — embed via HTML source
In srcDoc mode, you paste raw HTML directly into the Iframe widget. This is useful if you want to wrap the iframe in custom HTML or add styling.
- 1
Add an Iframe widget and switch to srcDoc
Drag an Iframe widget onto the canvas. In the property pane, change the source from URL to srcDoc.
- 2
Paste your HTML
In the srcDoc field, paste the following HTML:
<iframe src="https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID" width="100%" height="100%" frameborder="0" allow="clipboard-write" style="border: none;" ></iframe>
- 3
Deploy and test
Deploy your app and verify the widget loads correctly.
Note: The URL mode (Method 1) is simpler and recommended for most cases. Use srcDoc only if you need custom HTML wrapping or additional styling around the iframe.
Dynamic URL from Queries
Appsmith supports JavaScript bindings in widget properties. You can dynamically set the Iframe URL based on query results, API responses, or other widget values.
// Iframe URL property — dynamic binding
{{"https://embeddy.ai/webhost/" + Table1.selectedRow.widget_id + "?widget_props_id=" + Table1.selectedRow.props_id}}This binding updates the Iframe content whenever the user selects a different row in Table1. Any Appsmith query or widget reference can be used in the binding expression.
Iframe Widget Properties
Key properties you can configure on the Appsmith Iframe widget:
| Property | Description |
|---|---|
| URL | The URL to load in the iframe. Set this to your Embeddy Embed Link. |
| srcDoc | Raw HTML to render inside the iframe. Use instead of URL for custom HTML. |
| Title | Accessible title for the iframe element. |
| onMessageReceived | Event handler triggered when the iframe sends a postMessage to the parent. |
| Visible | Toggle visibility. Bind to a condition to show/hide the widget dynamically. |
Limitations
Self-hosted CSP restrictions
If you self-host Appsmith, your Content Security Policy (CSP) headers may block loading external iframes. You may need to add embeddy.ai to your frame-src CSP directive.
Widget must be publicly accessible
The iframe loads client-side, so your Embeddy widget must be published and publicly accessible.
postMessage limitations
While Appsmith supports onMessageReceived for iframe postMessage, Embeddy widgets do not currently send postMessage events. This event handler is available for future integrations.
Troubleshooting
Iframe shows "Refused to connect" or blank
Common causes:
- Widget not published. Publish it in the Embeddy dashboard.
- CSP blocking (self-hosted). Add embeddy.ai to your frame-src CSP directive.
- Binding error. Check for JavaScript errors in the URL binding (look for red highlights in the property pane).
Widget not updating when query changes
Ensure your URL binding uses the correct syntax: {{query.data.field}}. The iframe should auto-reload when the bound value changes. If not, try toggling the widget's visibility or adding a key binding.
srcDoc not rendering
Ensure you have switched the source mode from URL to srcDoc in the property pane. Also check that your HTML is valid and does not contain syntax errors.
Still stuck? Reach out on Discord or contact support.
FAQ
Does this work with Appsmith's free/community edition?
Yes. The Iframe widget is available on all Appsmith editions — Community (free), Business, and Enterprise.
Can I use dynamic URLs based on database queries?
Yes. Appsmith bindings let you reference query results, API responses, and widget values in the Iframe URL property. See the "Dynamic URL" section above.
Will the widget update automatically?
Yes. The iframe loads from the live URL. Changes published in the Embeddy dashboard are reflected immediately in your Appsmith app.
Ready to embed your widget?
Head to your Embeddy dashboard to create or find your widget, copy the Embed Link, and add it to your Appsmith app with an Iframe widget.