Iframe events

Beyond its initial configuration, Map Embedding speaks a small postMessage API. Your page sends commands into the iframe to switch the displayed content, and the embed posts a ready event back to your page once the map settles. Every message is an object with a type field prefixed mountaya:.

Sending commands

To change what the embed shows after it has loaded, post a message to the iframe's contentWindow. One command is available.

The command accepts optional display overrides alongside the id. Any field you include is applied; any you omit leaves the embed's current state unchanged. The override fields are camelCase: terrain, withOverlays and withTerrains (arrays of slugs), and the boolean toggles withCollectionItineraries, withCollectionZones, withDownloadControl, withNavigationControl, withOverlaysControl, withPreferencesControl, withProfileAnalysis, withProfileCharacteristics, withProfileElevation, and withStreetviewControl.

A minimal command looks like this:

{
  "type": "mountaya:setItinerary",
  "itineraryId": "itinerary_123"
}

With overrides, switching content and changing the terrain in one message:

{
  "type": "mountaya:setItinerary",
  "itineraryId": "itinerary_456",
  "terrain": "satellite",
  "withOverlays": ["hillshade", "steepness"]
}

Post the message to the iframe's contentWindow, targeting the embed's origin (https://app.mountaya.com).

const iframe = document.querySelector("#mountaya");

iframe.contentWindow.postMessage(
  { type: "mountaya:setItinerary", itineraryId: "itinerary_123" },
  "https://app.mountaya.com",
);

Listening for events

Once the map finishes loading, or settles with an error, the embed posts a single mountaya:ready event to the parent window. Listen for it with a message handler and key on the message type.

The ready event always carries these fields:

A successful ready event looks like this:

{
  "type": "mountaya:ready",
  "error": null,
  "bounds": [6.82, 45.8, 6.92, 45.95],
  "itineraryId": "itinerary_123",
  "terrain": "topo"
}

The embed posts the ready event with a wildcard target origin, so verify the message came from the Mountaya origin by checking event.origin before trusting it.

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.mountaya.com") {
    return;
  }

  if (event.data?.type !== "mountaya:ready") {
    return;
  }

  if (event.data.error) {
    console.error("Mountaya embed failed:", event.data.error);
    return;
  }

  console.log("Map ready, bounds:", event.data.bounds);
});

Next steps