> 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/events-reference.md).

# Events Reference

All events are subscribed to via `mwm_v2.add_action` inside an `mwm_v2.onload` callback. Every handler receives the same object: `{ map, config, features, markers, controls }`.

See [SDK Overview](/mapster-wp-maps-v2/developer/sdk-overview.md) for usage details.

## Lifecycle Events

These fire in order as the map initializes. Subscribe to whichever stage you need.

| Event               | Description                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `map:loaded`        | The map library has initialized and the map is ready. The `map` object is available.     |
| `style:loaded`      | The map's base style has finished loading.                                               |
| `data:fetched`      | Feature and config data has been fetched from the server.                                |
| `features:loaded`   | Features have been processed and are being added to the map.                             |
| `features:rendered` | All features are visible on the map. This is the safest point to interact with features. |

## Interaction Events

These fire in response to user actions on map features.

| Event               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `marker:click`      | A marker feature was clicked.                                            |
| `marker:mouseenter` | The cursor entered a marker feature.                                     |
| `marker:mouseout`   | The cursor left a marker feature.                                        |
| `layer:click`       | A layer feature (circle, line, polygon, symbol) was clicked.             |
| `layer:mousemove`   | The cursor moved over a layer feature.                                   |
| `layer:mouseout`    | The cursor left a layer feature.                                         |
| `popup:open`        | A popup was opened (from any trigger — click or hover, marker or layer). |
| `popup:close`       | A popup was closed.                                                      |
| `modal:open`        | A modal was opened from a popup button action.                           |

## Map State Events

These fire when the map's display or configuration changes at runtime.

| Event             | Description                                |
| ----------------- | ------------------------------------------ |
| `map:resize`      | The map container was resized.             |
| `style:set`       | The map style was changed.                 |
| `terrain:set`     | 3D terrain was enabled or changed.         |
| `globe:set`       | Globe projection was toggled.              |
| `projection:set`  | The flat map projection was changed.       |
| `interaction:set` | Map interactivity was enabled or disabled. |
| `features:update` | Features were updated after initial load.  |
| `controls:update` | All controls were refreshed.               |

## Notes

* Interaction event handlers receive `{ map, config, features, markers, controls }` — the same as all other events. Event-specific data (e.g. which feature was clicked) is not passed through the public API. To get that level of detail, attach listeners directly to the underlying `map` object using the native library API.
* Not all events are guaranteed to fire on every map depending on configuration (e.g. `terrain:set` only fires if 3D terrain is enabled).