# Handling map events Register an event lister for events that a map object dispatches. ## Discussion MapKit JS uses events that developers can implement to hook into points in the life cycle of the map, as well as user interactions. Your code can respond to events by registering an event listener. Events have a `target` property. The `target` of an event is the object dispatching that event. When you add an event listener to a map, the target is the map itself. The `select` and `deselect` events have an annotation or overlay property that reports the selected or deselected item. The `single-tap`, `double-tap`, and `long-press` events have `pointOnPage` and `domEvents` properties that provide more data about the user interactions. Event listeners receive a single argument that is an event object. The event objects are similar to native event objects, though calls to `event.preventDefault()` or `event.stopPropagation()` don’t halt some actions that trigger these events. Scrolling, zooming, and panning, as well as zooming or rotating after a long press, provide methods to halt or prevent interaction. ### Respond to map display events MapKit JS dispatches the following events that allow you to respond to changes in the map display and a person’s interactions with the map and its controls. - `region-change-start`: The map’s visible region is about to change. - `region-change-end`: The map’s visible region finishes changing. - `rotation-start`: The map’s rotation is about to change. - `rotation-end`: The map’s rotation finishes changing. - `scroll-start`: The map is about to scroll as a result of user interaction. - `scroll-end` : The map finishes scrolling as a result of user interaction. - `zoom-start` : The map is about to zoom as a result of user interaction. - `zoom-end` : The map finishes zooming as a result of user interaction. - `map-type-change`: A program event or a user interaction causes the map’s `mapType` ([`MapType`](/documentation/MapKitJS/MapType)) to change. ### Respond to annotation and overlay events MapKit JS sends [`MapAnnotationSelectionEvent`](/documentation/MapKitJS/MapAnnotationSelectionEvent),[`MapOverlaySelectionEvent`](/documentation/MapKitJS/MapOverlaySelectionEvent), and [`MapAnnotationDragEvent`](/documentation/MapKitJS/MapAnnotationDragEvent) events when a person interacts with the annotations and overlays you place on the map. Respond to these interactions by updating the map or providing more information about the overlay or annotation the person interacts with. - `select`: The framework sends a [`MapAnnotationSelectionEvent`](/documentation/MapKitJS/MapAnnotationSelectionEvent) or [`MapOverlaySelectionEvent`](/documentation/MapKitJS/MapOverlaySelectionEvent)when someone selects an annotation or an overlay. - `deselect`: The framework sends a [`MapAnnotationSelectionEvent`](/documentation/MapKitJS/MapAnnotationSelectionEvent) or [`MapOverlaySelectionEvent`](/documentation/MapKitJS/MapOverlaySelectionEvent)when someone deselects an annotation or an overlay. - `drag-start`: The framework sends a [`MapAnnotationDragEvent`](/documentation/MapKitJS/MapAnnotationDragEvent) when someone starts to drag an annotation. - `dragging`: The framework send a [`MapAnnotationDragEvent`](/documentation/MapKitJS/MapAnnotationDragEvent) when someone drags an annotation. The event has two properties. - `drag-end`: The framework send a [`MapAnnotationDragEvent`](/documentation/MapKitJS/MapAnnotationDragEvent) when someone finishes dragging an annotation. ### Respond to user location events MapKit JS sends [`MapUserLocationChangeEvent`](/documentation/MapKitJS/MapUserLocationChangeEvent) or [`MapUserLocationErrorEvent`](/documentation/MapKitJS/MapUserLocationErrorEvent) events to indicate changes in a person’s location. Use these events to adjust what the map displays or to trigger other responses in your app. - `user-location-change`: The framework sends a [`MapUserLocationChangeEvent`](/documentation/MapKitJS/MapUserLocationChangeEvent) event when [`showsUserLocation`](/documentation/MapKitJS/Map/showsUserLocation) is `true` and the map acquires the user’s location, or after an automatic update. - `user-location-error`: The framework sends a ([`MapUserLocationErrorEvent`](/documentation/MapKitJS/MapUserLocationErrorEvent)) when MapKit JS is unable to acquire the user’s location. ### Respond to map interaction events MapKit JS sends [`MapEvent`](/documentation/MapKitJS/MapEvent) events when someone taps or presses on the map view. Use these events to adjust the map view, respond to the deselecting of overlays, or drag or deselect annotations. - `single-tap`: The framework sends an event when a single tap occurs on the map outside an annotation or an overlay. If an annotation or an overlay is in a selected state when a single tap occurs, MapKit JS deselects the annotation or the overlay and dispatches a single-tap event. - `double-tap`: The framework sends an event when a double tap occurs on the map without zooming the map. - `long-press`: The framework sends an event when a long press occurs on the map outside an annotation. A long press may be the beginning of a panning or pinching gesture on the map. You can prevent the gesture from starting by calling the `preventDefault` method of the event. Annotations need to be draggable to dispatch long-press events. ## Topics ### Map events [`MapEvent`](/documentation/MapKitJS/MapEvent) An object that represents a gesture the framework recognized on the map. [`MapAnnotationDragEvent`](/documentation/MapKitJS/MapAnnotationDragEvent) An event object that the map object dispatches when someone drags an annotation. [`MapAnnotationSelectionEvent`](/documentation/MapKitJS/MapAnnotationSelectionEvent) An event object that the map object dispatches when someone selects or deselects an annotation. [`MapOverlaySelectionEvent`](/documentation/MapKitJS/MapOverlaySelectionEvent) An event object that the map view dispatches when someone selects or deselects an overlay. [`MapUserLocationChangeEvent`](/documentation/MapKitJS/MapUserLocationChangeEvent) An event that represents a change in a person’s location. [`MapUserLocationErrorEvent`](/documentation/MapKitJS/MapUserLocationErrorEvent) An event that indicates that MapKit JS is unable to acquire a person’s location. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)