> For the complete documentation index, see [llms.txt](https://wpmaps-docs.mapster.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wpmaps-docs.mapster.me/mapster-wp-maps-v2/developer/sdk-overview.md).

# SDK Overview

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:

```js
window.mwm_v2
```

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

```js
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:

```js
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](/mapster-wp-maps-v2/developer/events-reference.md) 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:

```js
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:

```js
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:

```js
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.