---
url: https://docs.ridgedata.ai/guide/getting-started.md
---
# 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](./iframe-authentication#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](./iframe)

## 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](./javascript)

## Shared concepts

Both use the same component ids, state format, published themes, and row-level
partitions. Learn more in [Dashboard state](./state),
[Filters](./filters), and [Partitioning](./partitioning).