Choose an embed

You can embed a Ridge dashboard with an iframe or JavaScript. Both display the same published dashboard. Choose based on how you want to authenticate viewers and control the dashboard.

	Iframe embed	JavaScript embed
Best for	Fast integration and strong isolation	Custom controls, theming, and image export
Browser receives	A signed Ridge URL	A short-lived JWT from your server
Credential lifecycle	Valid until revoked in Ridge	Expires after 24 hours; cannot be revoked individually
Renders in	Separate iframe document	Shadow root in your page
Initial state	state in the iframe URL	state passed when mounting
Runtime control	postMessage state protocol	State, filters, events, rendering status, and image export
Theming	Dashboard's published theme	Theme overrides for each embed
Host setup	An <iframe>	A backend token endpoint plus browser loader

Iframe replies and events are addressed to the origin of your app's first command; see Host origin.

Choose the iframe when

• you want to embed a dashboard with a single HTML tag;
• you want the dashboard in a separate document;
• a long-lived URL that can be revoked in Ridge fits your access model; or
• setting and reading state over postMessage is enough.

Add an iframe embed

Choose the JavaScript embed when

• your app needs to load and remove the dashboard as users navigate;
• you need filter events, rendering status, image export, or custom themes;
• your backend can create a JWT for each viewer, limited to the dashboards they can access; or
• you want to call JavaScript methods to control the dashboard.

The JavaScript embed authenticates through your server and renders inside a shadow root in your page.

Add a JavaScript embed

Shared concepts

Both use the same component ids, state format, published themes, and row-level partitions. Learn more in Dashboard state, Filters, and Partitioning.