Custom Markers

Custom markers let you replace the default Mapsted appearance for map entities, add markers at geographic coordinates, and place markers on map overlay elements. The API exposes four functions for this purpose, each covering a distinct placement target.

Note — no addMarker() / removeMarker() / clearMarkers()
These method names do not exist in the public API surface. Markers are data-driven: you pass an array (or a single object) describing your entities/coordinates/overlays to the relevant setter and the map re-renders. To "remove" a marker, call the setter again with an empty array or omit the marker field for that item.

Prerequisites

The library initialised and in the READY state (API lifecycle).
A propertyId whose buildings/floors are already loaded.

Marker field syntax

The marker field appears on MapEntity, CoordsData, and MapOverlayMarker alike. The runtime applies the following heuristic:

`marker` value	Rendered as
Starts with `"<"`	HTML string rendered inside the marker container
Any other string	Image URL (raster PNG/JPG or SVG; `data:` URIs accepted)

// HTML marker string
marker: '<div class="pulse-dot" aria-label="You are here"></div>'

// Image URL
marker: 'https://cdn.example.com/icons/star.png'

// Inline SVG via data URI
marker: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...'

Entity markers — override a Mapsted POI

Use setEntityData() to replace the marker (and optionally the popup content) for one or more Mapsted entities identified by their numeric/string IDs.

Type:MapEntity[]

type MapEntity = {
  id: MapstedId;        // entity id (string | number)
  name?: string;        // popup title
  html?: string;        // popup body HTML
  marker?: string;      // HTML string or image URL — see "Marker field syntax" above
  highlight?: HighlightStyle;
  buildingId?: string | number;
};

CDN

html

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

  // Override marker for two entities
  await mapsted.maps.setEntityData([
    {
      id: 5001,
      name: 'Coffee Cart',
      marker: '<div class="coffee-pin" aria-label="Coffee Cart"></div>',
    },
    {
      id: 5002,
      name: 'Information Desk',
      marker: 'https://cdn.example.com/icons/info.png',
    },
  ]);
</script>

npm

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

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

await maps.setEntityData([
  {
    id: 5001,
    name: 'Coffee Cart',
    marker: '<div class="coffee-pin" aria-label="Coffee Cart"></div>',
  },
  {
    id: 5002,
    name: 'Information Desk',
    marker: 'https://cdn.example.com/icons/info.png',
  },
]);

Passing a non-array value throws MAPSTED-1013

Override a single entity by ID

setEntityDataById() is a convenience wrapper when you only need to update one entity without constructing an array.

// CDN
await mapsted.maps.setEntityDataById(5001, {
  id: 5001,
  marker: '<div class="highlight-pin"></div>',
});

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

await maps.setEntityDataById(5001, {
  id: 5001,
  marker: '<div class="highlight-pin"></div>',
});

Both id and entity are validated; missing or non-object entity throws MAPSTED-1061

Set a default marker for all entities

setEntityDefaults() applies a single MapEntity object as the fallback appearance for every entity that does not have an explicit override set via setEntityData().

// CDN
await mapsted.maps.setEntityDefaults({
  id: 0, // id is required by the type but ignored for defaults
  marker: 'https://cdn.example.com/icons/default-pin.png',
});

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

await maps.setEntityDefaults({
  id: 0,
  marker: 'https://cdn.example.com/icons/default-pin.png',
});

Non-object input throws MAPSTED-1061

Coordinate markers — pin any lat/long position

setCoordsData() places markers at arbitrary geographic coordinates, independent of the Mapsted entity graph. Use this for live-location pins, search results, or external POIs.

Type:CoordsData[]

type CoordsData = {
  lat: number;     // WGS84 latitude
  long: number;    // WGS84 longitude  (canonical field name)
  floor: number;   // floor ID — marker only appears on this floor
  name?: string;   // popup title
  html?: string;   // popup body HTML
  marker?: string; // HTML string or image URL
};

Note: The canonical coordinate field is long. Passing lng instead is also accepted — the API normalizes lng to long internally — but prefer long as shown for clarity.

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.setCoordsData([
    {
      lat: 43.6532,
      long: -79.3832,
      floor: 3,
      name: 'You are here',
      marker: '<div class="user-dot" aria-label="Your location"></div>',
    },
  ]);
</script>

npm

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

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

await maps.setCoordsData([
  {
    lat: 43.6532,
    long: -79.3832,
    floor: 3,
    name: 'You are here',
    marker: '<div class="user-dot" aria-label="Your location"></div>',
  },
]);

Passing a non-array value throws MAPSTED-1013

To clear all coordinate markers, call setCoordsData([]).

Map overlay markers — attach a marker to a CMS overlay

setMapOverlayMarkers() places markers on named map overlay elements (zones, regions, or decorators) configured in the Mapsted CMS. The overlay id values come from the manage-cms dashboard.

Type:MapOverlayMarker[]

type MapOverlayMarker = {
  id: string;      // CMS map overlay ID
  name?: string;   // popup title
  html?: string;   // popup body HTML
  marker?: string; // HTML string or image URL
};

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: 'zone-food-court',
      name: 'Food Court',
      marker: 'https://cdn.example.com/icons/food.png',
    },
    {
      id: 'zone-parking-a',
      name: 'Parking A',
      marker: '<div class="parking-badge">P</div>',
    },
  ]);
</script>

npm

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

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

await maps.setMapOverlayMarkers([
  {
    id: 'zone-food-court',
    name: 'Food Court',
    marker: 'https://cdn.example.com/icons/food.png',
  },
  {
    id: 'zone-parking-a',
    name: 'Parking A',
    marker: '<div class="parking-badge">P</div>',
  },
]);

Passing a non-array value throws MAPSTED-1080 The library internally copies the array and maps id → mapOverlayId (no mutation of the caller's array).

Centre the map on an overlay

After placing an overlay marker you can programmatically pan the map to that overlay using centerOnMapOverlay():

// CDN
await mapsted.maps.centerOnMapOverlay('zone-food-court');

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

await maps.centerOnMapOverlay('zone-food-court');

Passing markers at init time

All four marker collections can be supplied directly to init() via InitOptions so the map renders them as part of first load:

`InitOptions` field	Equivalent post-init call
`entityData`	`setEntityData()`
`entityDefaults`	`setEntityDefaults()`
`coordsData`	`setCoordsData()`
`mapOverlayMarkers`	`setMapOverlayMarkers()`

CDN

html

<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({
    element: '#map',
    entityData: [
      { id: 5001, marker: 'https://cdn.example.com/icons/star.png' },
    ],
    coordsData: [
      { lat: 43.6532, long: -79.3832, floor: 3,
        marker: '<div class="user-dot"></div>' },
    ],
    mapOverlayMarkers: [
      { id: 'zone-food-court', marker: 'https://cdn.example.com/icons/food.png' },
    ],
  });
</script>

npm

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

await maps.init({
  element: '#map',
  propertyId: 1234,
  entityData: [
    { id: 5001, marker: 'https://cdn.example.com/icons/star.png' },
  ],
  coordsData: [
    { lat: 43.6532, long: -79.3832, floor: 3,
      marker: '<div class="user-dot"></div>' },
  ],
  mapOverlayMarkers: [
    { id: 'zone-food-court', marker: 'https://cdn.example.com/icons/food.png' },
  ],
});

Current public-API scope

The following capabilities are not part of the public JS API surface:

Dynamic marker removal by ID — there is no removeMarker(id). To remove a marker, call the corresponding setter with an updated array that omits the item (or pass [] to clear all).
Anchor / offset control — CoordsData and MapOverlayMarker do not expose an anchor or pixel-offset field. The rendering position relative to the coordinate is controlled by the map iframe internally.
Z-index / layer ordering — no public API for controlling marker stacking order.
Animation / transition — marker HTML can include CSS animations; no JS-driven animation API is exposed.

Note — CoordsData.long field name: CoordsData uses long rather than the conventional lng name used in ViewportOptions.mapCenter and standard geographic JS libraries. If you pass lng instead, the API accepts it and normalizes it to long — but for clarity and consistency with the examples above, prefer long.

Known limitation — setEntityDefaults() requires a placeholder id: The MapEntity type used by setEntityDefaults() includes a required id field that has no semantic meaning in a defaults context. Pass any integer (e.g. id: 0) as a placeholder. A dedicated EntityDefaults type that makes id optional is planned for a future release.

Use map overlay markers — setMapOverlayMarkers() + centerOnMapOverlay()
Implement idle detection for kiosk mode
InitOptions reference
API reference

Custom Markers ​

Prerequisites ​

Marker field syntax ​

Entity markers — override a Mapsted POI ​

CDN ​

npm ​

Override a single entity by ID ​

Set a default marker for all entities ​

Coordinate markers — pin any lat/long position ​

CDN ​

npm ​

Map overlay markers — attach a marker to a CMS overlay ​

CDN ​

npm ​

Centre the map on an overlay ​

Passing markers at init time ​

CDN ​

npm ​

Current public-API scope ​

Related ​

Custom Markers

Prerequisites

Marker field syntax

Entity markers — override a Mapsted POI

CDN

npm

Override a single entity by ID

Set a default marker for all entities

Coordinate markers — pin any lat/long position

CDN

npm

Map overlay markers — attach a marker to a CMS overlay

CDN

npm

Centre the map on an overlay

Passing markers at init time

CDN

npm

Current public-API scope

Related