SDK Overview

How to hook into Mapster WP Maps V2 as a developer.

Mapster WP Maps V2 exposes a JavaScript SDK that lets you interact with maps on the page — subscribing to lifecycle events, reacting to user interactions, and accessing the underlying map library object to make your own modifications.

The mwm_v2 Global

When the plugin loads on a page, it immediately creates a global object:

window.mwm_v2

This is your entry point as a developer. It has one method you'll use directly:

window.mwm_v2.onload(fn)

onload registers a function to be called once the SDK is ready to accept event subscriptions for each map instance. Code placed inside onload is guaranteed to run before any map events fire, so your listeners will catch everything from the beginning.

Subscribing to Events

Inside your onload callback, use mwm_v2.add_action to subscribe to events:

window.mwm_v2.onload(() => {
  window.mwm_v2.add_action('map:loaded', ({ map, config, features, markers, controls }) => {
    // the map is initialized — do something with it
    console.log(map);
  });
});

Every event handler receives the same object:

Property	Description
map	The underlying map library instance (MapLibre, Mapbox GL, or Google Maps)
config	The map's configuration object
features	Array of feature data loaded onto the map
markers	Marker instances currently on the map
controls	Control instances currently on the map

See Events Reference for the full list of available events.

Targeting a Specific Map

On pages with multiple maps, your onload callback runs once per map instance. Use config.id inside your handler to filter to the map you want:

window.mwm_v2.onload(() => {
  window.mwm_v2.add_action('map:loaded', ({ map, config }) => {
    if (config.id !== 42) return;
    // only runs for map with WordPress ID 42
  });
});

Custom Scripts

The Custom Scripts feature works the same as in V1. In the map's settings, enter the name of a global function. That function will be called automatically after the map loads, receiving map and features as arguments:

window.myCustomFunction = function(map, features) {
  console.log(map, features);
}

This is a simpler alternative to onload when you only need to target one specific map and don't need to subscribe to multiple events.

Accessing the Map Library

The map object passed to your handlers is the raw instance from whichever library the map is using — MapLibre GL JS, Mapbox GL JS, or the Google Maps API. You can call any method available in that library directly on it:

window.mwm_v2.onload(() => {
  window.mwm_v2.add_action('map:loaded', ({ map }) => {
    map.flyTo({ center: [-74.006, 40.7128], zoom: 12 });
  });
});

Refer to the relevant library's documentation for available methods.

Layer Names

If you're using MapLibre GL JS or Mapbox GL JS, feature types are rendered as layers (and sources of the same name) directly on the map object. You can target these with native methods like map.setPaintProperty(), map.on('click', layerName, ...), or map.getLayer().

Feature Type	Layer / Source Name
Circle	mapster-circles
Symbol	mapster-symbols
Line	mapster-lines
Polygon (Flat)	mapster-polygons
Polygon (3D)	mapster-extrusion-polygons
Pattern Polygon	mapster-pattern-polygons

Markers aren't a map layer — they're rendered as individual library Marker instances (available via the markers property) rather than a GeoJSON layer.

Image Polygons are added one layer per feature rather than a single shared layer, named fill-image-{featureId}-layer (source: fill-image-{featureId}), where featureId is the feature's Mapster ID.

If clustering is enabled for a feature type, its layer name gets a -cluster suffix (e.g. mapster-circles-cluster), or -{categoryID}-cluster when clustering by category.

This is not part of the public API and may change between versions — treat direct layer manipulation as an advanced/unsupported technique.