MapKit JS 5

Use the most up to date version of MapKit JS on your website.


This document includes release notes for updates to MapKit JS 5. You can learn more about MapKit JS version numbers and how to automatically link to the latest available version in Loading the Latest or a Specific Version of MapKit JS.


MapKit JS 5.29.0 improves accessibility, performance, and the appearance of controls when they are mirrored for right-to-left languages.


  • Improved the performance of importGeoJSON by ensuring that the main thread is never blocked.

  • Updated controls so that when a user clicks or taps a control that has focus, it retains focus.

  • Ensured that controls that mirror for right-to-left languages also mirror the pressed state of the zoom buttons.


MapKit JS 5.28.1 improves keyboard navigation, fixes memory leaks, and addresses developer feedback.


  • Improved keyboard navigation on the map type control.

  • Fixed Feedback ID 6790373 so MapKit JS defaults to HTTPS for CDN connections whenever possible.

  • Fixed a memory leak created when MapKit JS called destroy() while the user location error panel was visible.

  • Updated the list of POI Filtering categories, removing ReligiousSite and Playground. POI Filtering (introduced at WWDC 2019) becomes available in the fall of 2019.


MapKit JS 5.25.0 includes various improvements for controls, GeoJSON import, and annotation clusters.


  • MapKit JS controls (+/- buttons, compass, Legal link, and so on) are no longer affected by CSS on the enclosing page.

  • Updated the Legal link so it connects to HI-IN, IW-IL, and VI-VN localized pages when MapKit JS is running one of these languages.

  • Updated spacing on the Apple Maps logo.

  • Made various improvements to GeoJSON import, such as adding the ability to handle null geometries in Features, ensuring that an ItemCollection is returned even for single item imports, and improving error message reporting.

  • Improved clustering behavior when member annotations are on both sides of the antimeridian.

  • Ensured that annotationsInMapRect does not return cluster annotations, to match the behavior of annotations.


MapKit JS 5.24.0 includes various improvements, including changes to how the Apple Maps logo and Legal link are displayed.


  • Improved how marker annotations animate in and out of clusters.

  • Improved how annotation clusters are grouped, so that one annotation cluster never overlaps another.

  • The showItems function now updates the map region in a way that encloses annotation callouts visible on selected annotations, so that any callouts showing will not be cut off the edge of the map.

  • The Legal link is now always shown, for all map dimensions.

  • The Apple Maps logo in the lower left corner is now displayed on maps with dimensions of 200 x 100 pixels and larger.

  • The time to detect a long-press map event has been increased to 500 ms. See Handling Map Events for more information.

  • Improve how cameraZoomRange and cameraBoundary behave for users in China.


MapKit JS 5.23.1 includes new APIs for region and zoom limits, an updated Apple Maps logo, and more.

New Features

  • Added the cameraDistance property, which sets the altitude of the camera above the center of the map. A change to the map's camera distance can be animated with setCameraDistanceAnimated.

  • Added the cameraZoomRange property, which restricts zooming to a specified minimum and maximum camera distance. A change to the map's camera zoom range can be animated with setCameraZoomRangeAnimated.

  • Added the cameraBoundary property, which restricts panning to a specified coordinate region. A change to the map's camera boundary can be animated with setCameraBoundaryAnimated.

  • Enabled Directions support for users in China.

  • Updated logo in the lower left corner from the Apple icon to the icon beside the word "Maps".


  • Fixed issue where importGeoJSON would not import a GeometryCollection nested within a Feature.

  • Improved how the default marker annotation color is set depending on the map's colorScheme. Setting a marker annotation's color property to null sets a default color that matches the current colorScheme.

  • Updated the Legal link on the map to open a web page, instead of displaying a menu.


The MapKit JS 5.22.0 release adds improvements to browser support.

New Features

  • Added pinch-zoom on trackpad support for Chrome and Firefox.


  • Improved performance of mouse wheel zoom for Firefox on Windows.

  • Prevented nontouch events from firing during touch gestures in Firefox.


The MapKit JS 5.21.0 release includes a rotation gesture improvement.


  • Fixed bug where rotating the map with gesture was not working in Chrome on Android.


The MapKit JS 5.20.3 release includes bug fixes and performance improvements.


  • Fixed bug where https: was not selected for CDN URLs in some packaged and local environments. [48289622]

  • Improved annotation CSS to prevent collision with styles on host implementations.

  • Improved annotations to warn instead of throw an error in some selection and deselection cases.

  • Improved positioning logic for Annotation glyph text.

  • Improved performance of annotation image assets.

  • Fixed bug in callout where glyphImage was always used instead of selectedGlyphImage where appropriate.


The MapKit JS 5.19.1 release includes minor fixes and performance improvements.


The MapKit JS 5.18.0 release includes new map interaction events and bug fixes.

New Features

  • Added map interaction events (single-tap, double-tap, and long-press), which are dispatched by the map when the user does a single tap, a double tap, or a long press, but only when the gesture has no effect on the map (such as selecting an annotation or zooming in).


  • Updated the behavior of setters that cause a selection state to change. For example, setting a selected property or adding a selected annotation cannot be done within the callback of select or deselect event listeners. Doing so will throw an error.

  • Improved rotation animation when a map has padding.

  • Fixed issue where a language set by a property (instead of by the MapKitInitOptions) would be reset upon initialization.


The MapKit JS 5.17.1 release improves the behavior of rotation when a map has padding.


  • Fixed issue where rotation was reset after certain map interactions.

  • Fixed compass control to correctly rotate around the center when the map has padding.


The MapKit JS 5.16.0 release includes new APIs that let developers inset the collision rectangle of annotations.


  • Added support for insetting the collision rectangle of annotations with the padding property of Annotations.


The MapKit JS 5.15.0 release includes improvements to the display of annotation and overlay items.


  • Improved computation of scale to better respect the padding configuration around items.


MapKit JS 5.13.0 includes new APIs that allow you to present maps in various styles and choose the kind of units in which to display distance.

New Features


  • Improved adaptive behavior of annotations when the map type switches.

  • Fixed selection delay for annotations on a map with zoom disabled.


The MapKit JS 5.11.1 release includes bug fixes.


  • Cluster annotations display improvements when switching to Hindi and RTL languages.

  • Annotations clear from the map immediately when setting the annotations array to [].


The MapKit JS 5.10.2 release includes performance improvements and bug fixes.


  • Setting isScrollEnabled to false can disable scrolling for the enclosing web page on touch devices. [45583214]

  • navigator.geolocation.watchPosition is undefined. [44311161]

  • The Legal link has moved to the bottom-left of the map, next to the Apple logo.

  • Improved overall performance when there are hundreds of annotations on the map.

  • Improved gesture recognition to prevent accidental rotation.

  • Improved VoiceOver support for the compass control.

  • Fixed scenario where the compass image was requested too often.

  • Fixed zooming, rotation, and panning gestures in Chrome Beta 68.

  • Fixed error when map wrapped by a React component is destroyed.


MapKit JS 5.7.0 includes minor API changes, support for the new underlying map with Apple data in supported regions, annotation improvements, and more.

This update also introduces a MapKit JS Usage Dashboard to help monitor API usage against daily limits.

New Features

  • A new property on the mapkit object named maps. Map instances are added to this array when they are initialized and removed as soon as they are destroyed.

  • MapKit JS Usage Dashboard that reports the number map initializations and service calls made by your team.


Deprecated Features

  • The path property of the DirectionsResponse is now deprecated in favor of the new polyline property.