Appearance

Add Markers and Popups ​

Overlay custom markers and informational popups on top of the Mapsted indoor map. Markers can use plain HTML, an image URL, or both. Popups display a label and optional rich HTML when a marker is tapped.

Prerequisites ​

Steps ​

1. Prepare your entity data array ​

Each entry in entityData targets one map entity (room, POI, or corridor) by its id. You can find entity IDs by listening to the select event — see Map events. The IDs below are real entities on the University of Windsor demo property (603).

MapEntity is a flat object — there are no nested marker or popup sub-objects:

FieldTypeDescription
idMapstedIdEntity ID (required).
markerstringFlat string: HTML (starts with "<") or an absolute image URL (does not start with "<"). Not a nested object — { html } / { image } object shapes are not valid.
namestringText shown at the top of the popup heading.
htmlstringHTML rendered inside the popup body.
javascript
const entityData = [
  {
    id: 302,                    // Information 192 (CAW Student Centre · L1)
    marker: "<div class='my-marker'>!</div>",  // HTML string marker
    name: "Information 192",
    html: "<p>Open Mon–Fri, 9 am – 5 pm</p>"
  },
  {
    id: 3764,                   // Fairtrade Coffee (CAW Student Centre · L1)
    marker: "https://example.com/icons/cafe.png",  // image URL marker
    name: "Fairtrade Coffee",
    html: "<p>Grab a coffee on level 1 of the CAW Student Centre.</p>"
  }
];

2. Pass the array to setEntityData ​

Call setEntityData inside the onload callback so the map is fully initialized before the overlay is applied. A marker only renders when the user is viewing the floor where its entity lives — entity id: 302 is on level 1 of CAW Student Centre, so the demo also calls applyBoost({ building: 710, floor: 1355 }) to navigate the map automatically. In production you can omit applyBoost if your users land inside the relevant building via other navigation.

javascript
mapsted.maps.init({
  element: document.getElementById("mapsted-map"),
  propertyId: 603,
  onload: function () {
    mapsted.maps.setEntityData(entityData);
    // Navigate to the floor where the entities live so markers are visible.
    mapsted.maps.applyBoost({ building: 710, floor: 1355 });
  }
});
Open in Sandbox ↗

3. Add a custom HTML marker ​

Any valid HTML string works as the marker field. If the string starts with "<" the API renders it as HTML; otherwise it is treated as an image URL. Style it with inline styles or a stylesheet class.

html
<style>
  .my-marker {
    background: #e74c3c;
    color: #fff;
    border-radius: 50%;
    width: 28px;
    height: 28px;
    display: flex;
    align-items: center;
    justify-content: center;
    font-weight: bold;
    font-size: 14px;
    box-shadow: 0 2px 6px rgba(0,0,0,0.3);
  }
</style>

4. Add a marker with an image ​

Supply an absolute image URL as the marker string. The API detects that it does not start with "<" and treats it as an image URL, scaling it to fit the marker bounding box automatically.

javascript
{
  id: 1246,                     // H.C. Washroom 313 (Memorial Hall · F3)
  marker: "https://example.com/icons/restroom.png",  // image URL
  name: "H.C. Washroom 313",
  html: "<p>Accessible facilities available on floor 3 of Memorial Hall.</p>"
}

5. Target a specific entity by ID with setEntityDataById ​

When you only need to update a single entity without redefining the full array, use setEntityDataById. Pass the flat MapEntity shape (no nested sub-objects):

javascript
mapsted.maps.setEntityDataById(302, {
  marker: "<div class='my-marker'>i</div>",
  name: "Information 192 (updated)",
  html: "<p>Now open weekends too.</p>"
});
Open in Sandbox ↗

6. Reset all entity overrides ​

Call setEntityDefaults to remove all custom markers and popups and restore the map to its default appearance. The method requires a MapEntity object — pass { id: 0 } to reset all entities to the property-wide default (the id field is not used for a global reset; 0 is the conventional sentinel):

javascript
mapsted.maps.setEntityDefaults({ id: 0 });

defaults argument is required

Calling setEntityDefaults() with no argument throws MAPSTED-1061 ("defaults must be a MapEntity object"). Always pass at least { id: 0 }.

7. Open a popup programmatically ​

Use showPopup(entityId) to open the default entity popup without requiring a user tap. The view stays fixed — no camera pan or floor change occurs. Optionally pass { html } to override the popup body for this invocation.

javascript
// Open the built-in popup for entity 302 (Information 192) without moving the camera
await mapsted.maps.showPopup(302);

// Open a popup with a custom body override
await mapsted.maps.showPopup(302, { html: '<p>Custom popup content for this call</p>' });

The method throws:

  • MAPSTED-1012 — when entityId is null or undefined.
  • MAPSTED-1013 — when entityId is not a string or number.
  • MAPSTED-1090 — when the API is not in the READY state.

Overlay markers ​

The Mapsted Maps JavaScript API has a dedicated overlay-marker API for placing markers on map overlays (regions defined in the CMS) rather than on individual entities.

  • setMapOverlayMarkers(markers) — set an array of MapOverlayMarker objects. Each marker targets an overlay by its id (obtained from the CMS). Optional fields: name, html, marker (HTML string or image URL), lat/lng (WGS84 anchor; defaults to the overlay's polygon center).
  • centerOnMapOverlay(id) — pan and zoom the map to centre on the named overlay.
javascript
mapsted.maps.init({
  element: document.getElementById('mapsted-map'),
  onload: function () {
    mapsted.maps.setMapOverlayMarkers([
      {
        id: 'zone-a',
        name: 'Zone A',
        html: '<p>Main exhibit area</p>',
        marker: '<div class="zone-pin">A</div>',
      },
    ]);

    // Pan to the overlay after setting markers
    mapsted.maps.centerOnMapOverlay('zone-a');
  },
});

For a full reference on overlay markers including the MapOverlayMarker type shape and CMS setup, see Overlay markers.

Expected output ​

Custom circular red markers appear over the targeted rooms. Tapping a marker opens a popup card with the flat name field as a heading and the html field rendered below it. The popup closes when the user taps elsewhere on the map.

Next steps ​