Events

  • The Google Maps JavaScript API uses UI events for user interactions and MVC events for object state changes.

  • addListener() is used to handle both UI and MVC events, triggering callback functions upon event occurrence.

  • UI events provide details like mouse position, while MVC events require get methods to access changed property values.

  • Closures help manage private data within event listeners, as demonstrated with secret messages assigned to markers.

  • bounds_changed is recommended for detecting viewport changes, while avoiding setting properties within their own state change handlers to prevent infinite loops.
Select platform: Android iOS JavaScript

This page describes the user interface events and error events that you can listen for and handle programmatically.

User Interface Events

JavaScript within the browser is event driven, meaning that JavaScript responds to interactions by generating events, and expects a program to listen to interesting events. There are two types of events:

  • User events (such as "click" mouse events) are propagated from the DOM to the Maps JavaScript API. These events are separate and distinct from standard DOM events.
  • MVC state change notifications reflect changes in Maps JavaScript API objects and are named using a property_changed convention.

Each Maps JavaScript API object exports a number of named events. Programs interested in certain events will register JavaScript event listeners for those events and execute code when those events are received by calling addListener() to register event handlers on the object.

The following sample shows you which events are triggered by the google.maps.Map as you interact with the map.

For a complete list of events, consult the Maps JavaScript API Reference. Events are listed in a separate section for each object which contains events.

UI Events

Some objects within the Maps JavaScript API are designed to respond to user events such as mouse or keyboard events. For example, these are some of the user events that a google.maps.marker.AdvancedMarkerElement object can listen to:

  • 'gmp-click'
  • 'gmp-drag'
  • 'gmp-dragstart'
  • 'gmp-dragend'

For the full list, see the AdvancedMarkerElement class. These events may look like standard DOM events, but they are actually part of the Maps JavaScript API. Because different browsers implement different DOM event models, the Maps JavaScript API provides these mechanisms to listen for and respond to DOM events without needing to handle the various cross-browser peculiarities. These events also typically pass arguments within the event noting some UI state (such as the mouse position).

MVC State Changes

MVC objects typically contain state. Whenever an object's property changes, the Maps JavaScript API will fire an event that the property has changed. For example, the API will fire a zoom_changed event on a map when the map's zoom level changes. You can intercept these state changes by calling addListener() to register event handlers on the object as well.

User events and MVC state changes may look similar, but you should treat them differently in your code. MVC events, for example, don't pass arguments within their event. Inspect the property that changed on an MVC state change by calling the appropriate getProperty method on that object.

Handle Events

To register for event notifications, use the addListener() event handler. That method takes an event to listen for, and a function to call when the specified event occurs.

Example: Map and Marker Events

The following code mixes user events with state change events. This example attaches an event handler to a marker that zooms the map when clicked. It also attaches an event handler to the map for changes to the center property and pans the map back to the marker after 3 seconds on receipt of the center_changed event.

TypeScript

async function init() {
    // Request needed libraries.
    const