Appearance

Use Map Overlay Markers ​

Map overlay markers are a specialized layer of markers managed as a batch — designed for use cases where you need to pin many items at once and optionally center the map on one of them. Typical examples include search results, promotional highlights, or real-time asset positions.

Open in Sandbox ↗

Overlay markers are set as a complete array via setMapOverlayMarkers, replacing whatever was previously displayed. This makes them easy to refresh as your underlying data changes.

Prerequisites ​

  • The library initialized and in the READY state (API lifecycle)
  • Each marker must have an id string obtained from Mapsted CMS (Manage) that corresponds to the target map overlay

MapOverlayMarker shape ​

Each element of the markers array must conform to MapOverlayMarker:

FieldTypeRequiredDescription
idstringYesCMS map-overlay ID (obtain from Mapsted Manage). Internally aliased to mapOverlayId before dispatch.
namestringNoText shown at the top of the overlay popup.
htmlstringNoHTML string rendered inside the popup. Checked for data-mapsted-attributes.
markerstringNoImage URL or inline HTML for the pin icon. Strings not starting with "<" are treated as image URLs.
latnumberNoWGS84 latitude. Use with lng to anchor the marker at a specific coordinate instead of the mapoverlay shape's polygon center.
lngnumberNoWGS84 longitude. Required together with lat.

Positioning: when both lat and lng are provided, the iframe anchors the marker at that coordinate. Omit both (or only provide one) to fall back to the legacy behavior: the marker anchors to the center of the underlying mapoverlay shape (polygon).

Setting overlay markers ​

CDN ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });

  await mapsted.maps.setMapOverlayMarkers([
    {
      id: 'cms-overlay-abc',        // CMS map overlay ID from Mapsted Manage
      name: 'Coffee Shop',
      marker: 'https://cdn.example.com/icons/coffee.png',
    },
    {
      id: 'cms-overlay-def',
      name: 'Pharmacy',
      marker: 'https://cdn.example.com/icons/pharmacy.png',
    },
  ]);
</script>

npm ​

js
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
});

await maps.setMapOverlayMarkers([
  {
    id: 'cms-overlay-abc',          // CMS map overlay ID from Mapsted Manage
    name: 'Coffee Shop',
    marker: 'https://cdn.example.com/icons/coffee.png',
  },
  {
    id: 'cms-overlay-def',
    name: 'Pharmacy',
    marker: 'https://cdn.example.com/icons/pharmacy.png',
  },
]);

setMapOverlayMarkers validates that markers is an array (throws MAPSTED-1080 otherwise) and transforms each entry to alias id → mapOverlayId without mutating the caller's array before dispatching the update to the iframe.

Centering on a specific overlay marker ​

After setting overlay markers, call centerOnMapOverlay with the marker's id string to pan and zoom the camera to that item:

CDN ​

html
<script>
  await mapsted.maps.centerOnMapOverlay('cms-overlay-abc');
</script>

npm ​

js
await maps.centerOnMapOverlay('cms-overlay-abc');

centerOnMapOverlay requires a non-empty string; passing null, undefined, or an empty string throws MAPSTED-1012.

You can combine this with a user-selection flow — for example, centering the map whenever the user taps a search result in your sidebar:

js
// npm example
resultsList.addEventListener('click', (e) => {
  const item = e.target.closest('[data-overlay-id]');
  if (item) {
    maps.centerOnMapOverlay(item.dataset.overlayId);
  }
});

Handling overlay marker selection events ​

When the user taps/clicks an overlay marker inside the map, the API emits mapOverlayMarkerSelect. The payload is an object (not a raw string):

ts
{
  mapOverlayId: string;  // CMS overlay ID of the tapped marker
  name?: string;         // name set on the MapOverlayMarker, if any
  marker?: string;       // marker HTML/URL set on the MapOverlayMarker, if any
  lat?: number;          // latitude set on the MapOverlayMarker, if any
  lng?: number;          // longitude set on the MapOverlayMarker, if any
}

Always destructure to extract mapOverlayId — treating the payload as a raw string will produce [object Object].

CDN ​

html
<script>
  mapsted.maps.on('mapOverlayMarkerSelect', ({ mapOverlayId, name, lat, lng }) => {
    console.log('Selected overlay:', mapOverlayId, name ?? '');
    highlightSidebarItem(mapOverlayId);
  });
</script>

npm ​

js
import * as maps from '@mapsted/maps-js-api';

maps.on('mapOverlayMarkerSelect', ({ mapOverlayId, name, lat, lng }) => {
  console.log('Selected overlay:', mapOverlayId, name ?? '');
  highlightSidebarItem(mapOverlayId);
});

on is exported from the emitter module and returns an Unsubscribe function you can call to detach the handler.

Clearing overlay markers ​

Pass an empty array to remove all overlay markers:

CDN ​

html
<script>
  await mapsted.maps.setMapOverlayMarkers([]);
</script>

npm ​

js
await maps.setMapOverlayMarkers([]);

Updating markers in real time ​

Because setMapOverlayMarkers replaces the entire set, refreshing is straightforward:

js
// npm example
async function refreshOverlays() {
  const assets = await fetchLiveAssets(); // your data source

  // Each item's `cmsOverlayId` must be a valid Mapsted Manage overlay ID
  await maps.setMapOverlayMarkers(
    assets.map((a) => ({
      id: a.cmsOverlayId,
      name: a.label,
      marker: assetIconUrl(a.type),
    }))
  );
}

// Refresh every 10 seconds
setInterval(refreshOverlays, 10_000);

Passing markers at init time ​

mapOverlayMarkers can also be set directly on InitOptions — the API applies transformMapOverlayMarkers during the INITIALISE_MAP phase:

js
// npm example
await maps.init({
  element: '#map',
  propertyId: 1234,
  mapOverlayMarkers: [
    { id: 'cms-overlay-abc', name: 'Coffee Shop' },
  ],
});

Known API changes ​

lat / lng fields on MapOverlayMarker (added in 4.0.1): Callers can now anchor an overlay marker at an explicit WGS84 coordinate without using setCoordsData. See the shape table above.

mapOverlayMarkerSelect payload enriched (4.0.1): The mapOverlayMarkerSelect payload now carries { mapOverlayId, name?, marker?, lat?, lng? } reflecting whatever metadata was set on the underlying MapOverlayMarker. See the events reference and CHANGELOG for the migration note.