Events

Both embed types report when they are ready, when state changes, and when an update is rejected. Iframes send window messages. JavaScript embeds let you register event listeners on the dashboard handle.

The JavaScript API also reports filter changes and identifies whether a change came from the user or your app. It provides methods to wait for rendering and export images.

In the iframe examples, replies and events are addressed to the origin of your first command after ridge:ready; see Host origin.

Ready

Iframe

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow || event.origin !== ridgeOrigin) return;
  if (event.data?.type === "ridge:ready") {
    console.log("Dashboard ready", event.data.stateSchema);
  }
});

JavaScript

ridge.on("statechange", ({ state }) => console.log(state)); // safe before ready
await ridge.ready;
console.log("Dashboard ready", ridge.getStateSchema());

Register an iframe message listener before loading the frame so its one-time ridge:ready message cannot be missed. For JavaScript embeds, attach listeners as soon as the loader returns, before awaiting ready.

State changes

Iframe

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow || event.origin !== ridgeOrigin) return;
  if (event.data?.type === "ridge:stateChange") {
    syncMyControls(event.data.state);
  }
});

JavaScript

const unsubscribe = ridge.on("statechange", ({ state, changes, source }) => {
  if (source === "user") syncMyControls(state, changes);
});

// Later:
unsubscribe();

The iframe reports the complete resulting state. The JavaScript event also reports which values changed, and whether the change came from the user or API.

Filter changes

Iframe

// Filters arrive inside ridge:stateChange like any other state key.
const region = event.data.state["region-menu"]?.filter;

JavaScript

ridge.on("filterchange", ({ filters, changes, source }) => {
  if (source === "user") syncFilterControls(filters, changes);
});

Use { silent: true } to update state without sending a change notification to your app.

Rejected writes

Iframe

if (event.data?.type === "ridge:error") {
  const { id, code, message } = event.data.error;
  console.warn(code, id, message);
}

JavaScript

ridge.on("stateerror", ({ id, code, message }) => {
  console.warn(code, id, message);
});

Use code to identify the error in your handler. Some updates in a batch may succeed even when another component rejects its value.

Export an image

Use the JavaScript API to export the dashboard as an image. It is not available through iframe messages:

Iframe

Not supported by the iframe message protocol.

JavaScript

const png = await ridge.exportImage("png");
const blob = await ridge.exportImage("blob");

exportImage waits for the dashboard's queries and rendering to finish, so the image includes the latest state.

Image export results

exportImage(type)	Result
"png" (default)	PNG data URL string, usable as an image's src.
"jpeg"	JPEG data URL string.
"svg"	SVG data URL string.
"blob"	PNG Blob. Use URL.createObjectURL(blob) for an image URL, then revoke it when no longer needed.
"pixelData"	Uint8ClampedArray of RGBA pixel values.

The result can be null if no dashboard image is available. Export failures can reject the promise; handle them with try/catch.

JavaScript event names

Event	Payload type	Contents
statechange	StateChangeEvent	Complete state, changed values in changes, and source ("user" or "api").
filterchange	FilterChangeEvent	Active filters, changed filters in changes, and source.
stateerror	StateError	Component id, error code, and message for a rejected update.

ridge.on(name, listener) returns a function that removes the listener. The RidgeEmbedEventMap reference maps each event name to its payload type.