Embedding

Widget.js Reference

Use the JavaScript widget for advanced embedding with cross-domain communication.

Widget.js Reference

The Mapsemble widget is a lightweight JavaScript file that creates and manages an embedded map iframe, with built-in support for cross-domain communication between your page and the map.

Basic usage

Add the script tag and a container element to your HTML:

<script src="https://app.mapsemble.com/widget.js"></script>
<div data-mapsemble-map="YOUR_MAP_ID"></div>

That's it. The widget will automatically create the iframe and set up communication.

How it works

When widget.js loads, it:

  1. Finds all elements on the page with a data-mapsemble-map attribute
  2. Creates an iframe for each element, pointing to the embed URL for that map ID
  3. Sets up postMessage communication between your page and the embedded map

Cross-domain communication

The widget uses the browser's postMessage API to communicate between your page and the embedded map iframe. The following message types are emitted by the map:

  • FILTERS_UPDATE — Fired when the user changes a filter inside the map. Use this to sync filter state with your own UI.
  • PAGE_UPDATE — Fired when the user navigates to a different page in the list view.
  • EXTENT_UPDATE — Fired when the map viewport changes (pan or zoom). Returns the new bounding box coordinates.
  • iframeScrollForward — Passes scroll events from inside the iframe to the parent page, ensuring smooth scrolling behavior.

Dimension negotiation

The widget supports automatic iframe height adjustment so the map fits its content without scrollbars:

  1. The parent page sends a DIMENSIONS_REQUEST message to the iframe
  2. The iframe responds with a DIMENSIONS_RESPONSE message containing { height, width }
  3. The widget resizes the iframe accordingly

This is handled automatically — no additional code is needed on your part.

Remote content script

Internally, a remoteContent.js script runs inside the iframe to handle:

  • Input focus management — Important for mobile devices, especially Android, where keyboard visibility affects layout
  • Dimension negotiation — Measures the iframe content and communicates the required size back to the parent

You do not need to include this script manually; it is loaded automatically by the embedded map.

Mobile considerations

The widget includes specific handling for mobile devices:

  • Android keyboard visibility — When a user focuses an input inside the map (e.g., a search filter), the widget sends INPUT_FOCUS and INPUT_BLUR messages to adjust the iframe layout and prevent the keyboard from obscuring content.
  • Scroll forwarding — Touch scroll events inside the iframe are forwarded to the parent page, ensuring smooth scrolling on mobile devices without the iframe "trapping" the scroll.

Multiple maps on one page

You can embed multiple maps on the same page. Each element with a data-mapsemble-map attribute creates a separate, independent iframe:

<script src="https://app.mapsemble.com/widget.js"></script>

<div data-mapsemble-map="MAP_ID_1"></div>
<div data-mapsemble-map="MAP_ID_2"></div>

Each map manages its own state and communication channel independently.