Events
Events control an embedded Mountaya map at runtime: switch content, change terrains, toggle overlays, and override display controls without reloading the iframe. The iframe also emits events back to the parent window to signal readiness.
Two flows run side by side:
- Inbound (parent → iframe): your page sends structured payloads via
iframe.contentWindow.postMessage()to control the map. - Outbound (iframe → parent): the iframe posts back lifecycle events like
mountaya:readyso your page can sync UI state.
Every inbound message must include a type field that identifies the action.
For security, restrict the targetOrigin (second argument of postMessage) to your embed domain instead of "*". For example: iframe.contentWindow.postMessage(payload, "https://app.mountaya.com").
Inbound messages
Messages sent from the parent window to the iframe.
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "bb908a79-dcc1-4db2-aba8-7238dd8f15fc",
}, "https://app.mountaya.com");Every field besides type and the content identifier (itineraryId or routeId) is optional. Omitted fields are left unchanged from the previous state.
Required fields
Identifies the action to perform. Determines which content identifier is required.
Kind: postMessage field
Key:
typeType:
stringSupported values:
"mountaya:setItinerary"
"mountaya:setRoute"Example:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
}, "https://app.mountaya.com");The itinerary to display. Required when type is mountaya:setItinerary.
Kind: postMessage field
Key:
itineraryIdType:
string (uuid)Example:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "bb908a79-dcc1-4db2-aba8-7238dd8f15fc",
}, "https://app.mountaya.com");The route to display. Required when type is mountaya:setRoute.
Kind: postMessage field
Key:
routeIdType:
string (uuid)Example:
iframe.contentWindow.postMessage({
type: "mountaya:setRoute",
routeId: "b61e7f93-fa79-4326-9a30-937e53d110c6",
}, "https://app.mountaya.com");Optional fields
Map's default state
Switches the base map terrain alongside a content change.
Kind: postMessage field
Key:
terrainType:
stringSupported terrains:
"satellite"
"topo"
"winter"Example:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
terrain: "winter",
}, "https://app.mountaya.com");Restricts which overlays appear in the layers panel. A wildcard (["*"]) enables all overlays. If both withOverlays and withTerrains are empty, the Layers panel is hidden.
Kind: postMessage field
Key:
withOverlaysType:
string[] | ["*"]Supported overlays:
"aspectslope"
"avalanche"
"hillshade"
"humidity"
"pois"
"snowdepth"
"snowfall-daily"
"snowfall-hourly"
"temperature-actual"
"temperature-perceived"
"temperature-soil"
"visibility"
"wind"Example:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withOverlays: ["hillshade", "temperature-actual", "wind"],
}, "https://app.mountaya.com");Restricts which terrains appear in the layers panel. A wildcard (["*"]) enables all terrains. If both withOverlays and withTerrains are empty, the Layers panel is hidden.
Kind: postMessage field
Key:
withTerrainsType:
string[] | ["*"]Supported terrains:
"satellite"
"topo"
"winter"Example:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withTerrains: ["topo", "satellite"],
}, "https://app.mountaya.com");Custom user experience
Shows or hides drawings from the collection tile layer.
Kind: postMessage field
Key:
withCollectionDrawingsType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withCollectionDrawings: true,
}, "https://app.mountaya.com");Shows or hides itineraries from the collection tile layer.
Kind: postMessage field
Key:
withCollectionItinerariesType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withCollectionItineraries: false,
}, "https://app.mountaya.com");Shows or hides routes from the collection tile layer.
Kind: postMessage field
Key:
withCollectionRoutesType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withCollectionRoutes: false,
}, "https://app.mountaya.com");Shows or hides the download button, allowing users to download the active route or itinerary as GPX or GeoJSON.
Kind: postMessage field
Key:
withDownloadControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withDownloadControl: true,
}, "https://app.mountaya.com");Shows or hides the flyover button, which plays a cinematic camera tour of the active route or itinerary inside the iframe. Video export and social share actions are only available in the Mountaya web app and are intentionally not exposed to embedded iframes.
Kind: postMessage field
Key:
withFlyoverControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withFlyoverControl: true,
}, "https://app.mountaya.com");Enables or disables map interactivity: zoom, pan within boundaries, and pitch adjustment.
Kind: postMessage field
Key:
withInteractionControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withInteractionControl: true,
}, "https://app.mountaya.com");Shows or hides the zoom and bearing controls at the top-right of the map. Disabled if withInteractionControl is also disabled.
Kind: postMessage field
Key:
withNavigationControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withNavigationControl: true,
}, "https://app.mountaya.com");Shows or hides the history and forecast layer control.
Kind: postMessage field
Key:
withOverlaysControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withOverlaysControl: true,
}, "https://app.mountaya.com");Shows or hides the Preferences panel, allowing users to change their preferred unit of length and temperature.
Kind: postMessage field
Key:
withPreferencesControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withPreferencesControl: true,
}, "https://app.mountaya.com");Shows or hides the terrain analysis (surface and way type) for the active route. Requires withProfileElevation to be enabled.
Kind: postMessage field
Key:
withProfileAnalysisType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withProfileAnalysis: true,
}, "https://app.mountaya.com");Shows or hides the characteristics display for the active route.
Kind: postMessage field
Key:
withProfileCharacteristicsType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withProfileCharacteristics: true,
}, "https://app.mountaya.com");Shows or hides the elevation profile for the active route.
Kind: postMessage field
Key:
withProfileElevationType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withProfileElevation: true,
}, "https://app.mountaya.com");Shows or hides the summary headline for the active route in the iframe header.
Kind: postMessage field
Key:
withProfileHeadlineType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withProfileHeadline: true,
}, "https://app.mountaya.com");Shows or hides the photos section in the profile.
Kind: postMessage field
Key:
withProfilePhotosType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withProfilePhotos: true,
}, "https://app.mountaya.com");Shows or hides the scale control at the bottom-left of the map.
Kind: postMessage field
Key:
withScaleControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withScaleControl: true,
}, "https://app.mountaya.com");Shows or hides the Street View button.
Kind: postMessage field
Key:
withStreetviewControlType:
booleanExample:
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
itineraryId: "uuid",
withStreetviewControl: true,
}, "https://app.mountaya.com");Outbound messages
Messages sent from the iframe to the parent window. Attach a message listener on window to react to them.
Always validate event.origin === "https://app.mountaya.com" before acting on a message. Never trust messages from unknown origins.
Emitted when the map has fully finished loading its current content. Fires on the initial load, and again after each mountaya:setItinerary or mountaya:setRoute message once the new content has rendered.
Useful to disable segmented controls, tabs, or other UI that switches content while the map is still loading, and re-enable it once the map is ready. The payload mirrors the currently resolved content so the parent can keep its own state in sync without round-tripping through other events.
Kind: postMessage event (iframe → parent)
Payload:
{
type: "mountaya:ready",
itineraryId: string | null,
routeId: string | null,
terrain: string,
bounds: [west: number, south: number, east: number, north: number] | null,
error: "timeout" | "not_found" | null,
}Fields:
itineraryId: active itinerary UUID, ornullwhen no itinerary is loaded.routeId: active route UUID, ornullwhen no route is loaded.terrain: slug of the active terrain (for exampletopo,satellite,winter).bounds: current map viewport as[west, south, east, north]in WGS84 degrees.nullwhen the map never resolved a successful load (seeerror).error:nullon a successful load,"timeout"when the 10s safety timeout fired before the requested content resolved, or"not_found"when the requested route or itinerary could not be located. The field is always present so consumers can rely on a stable shape.
Example:
window.addEventListener("message", (event) => {
if (event.origin !== "https://app.mountaya.com") return;
if (event.data?.type !== "mountaya:ready") return;
const { itineraryId, routeId, terrain, bounds, error } = event.data;
if (error !== null) {
console.warn("Embed finished loading with error:", error);
return;
}
// Map has finished loading — re-enable UI, sync parent state, etc.
console.log("Ready", { itineraryId, routeId, terrain, bounds });
});Full example
A complete example showing tabs that switch between itineraries with different display configurations.
const EMBED_ORIGIN = "https://app.mountaya.com";
const iframe = document.querySelector("iframe");
const examples = [
{
itineraryId: "bb908a79-dcc1-4db2-aba8-7238dd8f15fc",
terrain: "topo",
withOverlays: ["hillshade", "avalanche", "aspectslope", "wind"],
withStreetviewControl: false,
withTerrains: ["topo", "satellite"],
},
{
itineraryId: "1b2a36f4-2ef4-49bc-89db-814ee7de3ebc",
terrain: "topo",
withOverlays: ["temperature-actual", "humidity", "wind", "pois"],
withStreetviewControl: true,
withTerrains: ["topo", "satellite"],
},
{
itineraryId: "fbb1f6c2-345b-4f10-8387-6e60617ef894",
terrain: "winter",
withOverlays: ["*"],
withStreetviewControl: false,
withTerrains: ["winter"],
},
];
function switchTab(index) {
const example = examples[index];
iframe.contentWindow.postMessage({
type: "mountaya:setItinerary",
...example,
}, EMBED_ORIGIN);
}