Mapbox iOS SDK

The Mapbox iOS SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the Mapbox Style Specification, applies them to vector tiles that conform to the Mapbox Vector Tile Specification, and renders them using OpenGL.

Mapbox iOS SDK screenshots

For setup information, check out the Mapbox iOS SDK homepage. For detailed usage instructions, read “First steps with the Mapbox iOS SDK” and consult the online examples. A full changelog is also available.

If you have any questions, please contact our support team. We welcome your bug reports and feature requests.

Changes in version 3.4.0


  • Xcode 7.3 or above is required for using this SDK. (#6059)
  • Fixed an issue with symbols not being properly stripped from the dynamic framework. The dSYM file included with the standard dynamic framework in previous releases (e.g., or the Mapbox-iOS-SDK pod) could not be used to symbolicate crashes. (#6531)
  • Simulator architecture slices are included in the included dSYM file, allowing you to symbolicate crashes that occur in the Simulator. (#5740)
  • Clarified that the -ObjC linker flag is required for linking against the static framework distribution of this SDK. (#6213)
  • Added documentation for the Info.plist keys used by this SDK. (#6833)

Styles and data

  • A new runtime styling API allows you to adjust the style and content of the base map dynamically. All the options available in Mapbox Studio are now exposed via MGLStyle and subclasses of MGLStyleLayer and MGLSource. (#5727)
  • MGLMapView’s styleURL property can now be set to an absolute file URL. (#6026)
  • GeoJSON sources specified by the stylesheet at design time now support cluster, clusterMaxZoom, and clusterRadius attributes for clustering point features on the base map. (#5724)
  • Added quadkey support and limited WMS support in raster tile URL templates. (#5628)
  • TileJSON manifests can now specify "scheme": "tms" to indicate the use of TMS coordinates. (#2270)
  • Fixed an issue causing abstract MGLMultiPointFeature objects to be returned in feature query results. Now concrete MGLPointCollectionFeature objects are returned. (#6742)
  • Fixed rendering artifacts and missing glyphs that occurred after viewing a large number of CJK characters on the map. (#5908)
  • -[MGLMapView resetPosition] now resets to the current style’s default center coordinates, zoom level, direction, and pitch, if specified. (#6127)
  • Fixed an issue where feature querying sometimes failed to return the expected features when the map was tilted. (#6773)
  • MGLFeature’s attributes and identifier properties are now writable. (#6728)
  • The text-pitch-alignment property is now supported in stylesheets for improved street label legibility on a tilted map. (#5288)
  • The icon-text-fit and icon-text-fit-padding properties are now supported in stylesheets, allowing the background of a shield to automatically resize to fit the shield’s text. (#5334)
  • The circle-pitch-scale property is now supported in stylesheets, allowing circle features in a tilted base map to scale or remain the same size as the viewing distance changes. (#5576)
  • The identifier property of an MGLFeature may now be either a number or string. (#5514)
  • If MGLMapView is unable to obtain or parse a style, it now calls its delegate’s -mapViewDidFailLoadingMap:withError: method. (#6145)
  • Added the -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] delegate method, which offers the earliest opportunity to modify the layout or appearance of the current style before the map view is displayed to the user. (#6636)
  • Fixed crashes that could occur when loading a malformed stylesheet. (#5736)
  • Fixed an issue causing stepwise zoom functions to be misinterpreted. (#6328)
  • A source’s tiles are no longer rendered when the map is outside the source’s supported zoom levels. (#6345)
  • Improved style parsing performance. (#6170)
  • Improved feature querying performance. (#6514)
  • Fixed an issue where shapes that cannot currently be visually represented as annotations were still shown on the map as point annotations. (#6764)

User location

  • The user dot now animates between user locations when user tracking is disabled. (#6215)
  • To customize the appearance of the user location annotation, subclass the newly added MGLUserLocationAnnotationView class and implement -[MGLMapViewDelegate mapView:viewForAnnotation:]. (#5882)
  • -[MGLMapView viewForAnnotation:] now returns the user location annotation view when given the user location annotation. (#6957)
  • Fixed an issue causing the user dot’s accuracy ring to wobble while zooming in and out. (#6019)
  • Heading accuracy indicator sizing has been changed to appear more precise. (#6120)
  • Fixed an issue that caused the map to not update to reflect the centerOffset when the user location was tracked. (#6216)


  • Added new methods to MGLMultiPoint for changing or appending vertices along polyline annotations and the exteriors of polygon annotations. (#6565)
  • Added new APIs to MGLMapView to query for visible annotations. Combined with -[MGLMapView viewForAnnotation:], these APIs can be used to access all visible annotation views. (6061)
  • Fixed an issue causing offscreen annotation views to be updated even when they were in the reuse queue. (#5987)
  • Fixed an issue preventing MGLAnnotationView from animating when its coordinate changes. (#6215)
  • Fixed an issue causing the wrong annotation view to be selected when tapping an annotation view with a center offset applied. (#5931)
  • Fixed an issue that assigned annotation views to polyline and polygon annotations. (#5770)
  • Per documentation, the first and last coordinates in an MGLPolygon must be identical in order for the polygon to draw correctly. The same is true for an MGLPolygon’s interior polygon. (#5514)
  • To make an MGLPolyline or MGLPolygon span the antimeridian, specify coordinates with longitudes greater than 180° or less than −180°. (#6088)
  • Deprecated -[MGLMapViewDelegate mapView:alphaForShapeAnnotation:] in favor of specifying an alpha component via -[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:] or -[MGLMapViewDelegate mapView:fillColorForPolygonAnnotation:]. (#6706)
  • Fixed an issue that caused an annotation view to disappear if it isn’t created using the annotation view reuse queue. (#6485)
  • Fixed an issue that could reset user-added transformations on annotation views. (#6166)
  • Improved the performance of relocating a non-view-backed point annotation by changing its coordinate property. (#5385)
  • Improved the precision of annotations at zoom levels greater than 18. (#5517)

Networking and offline maps

  • Fixed an issue preventing an MGLMapView from loading tiles while an offline pack is downloading. (#6446)
  • Fixed a crash that sometimes occurred when initializing an MGLMapView. (#5932)
  • Fixed a crash that could occur when the device is disconnected while downloading an offline pack. (#6293)
  • Fixed a crash that occurred when encountering a rate-limit error in response to a network request. (#6223)
  • Fixed an issue causing an MGLOfflinePack’s progress to continue to update after calling -suspend. (#6186)
  • Fixed an issue preventing cached annotation images from displaying while the device is offline. (#6358)
  • Added support for an MGLMapboxAPIBaseURL key in an app’s Info.plist in order to customize the base URL used for retrieving map data, styles, and other resources. (#6709)
  • Query parameters are no longer stripped from mapbox: URLs used as resource URLs. (#6182, #6432)
  • Database errors are now logged to the console. (#6291)

Other changes

  • Raster tiles such as those from Mapbox Satellite are now cached, eliminating flashing while panning back and forth. (#7091)
  • Improved the performance of symbol style layers. (#7025)
  • As the user zooms in, tiles from lower zoom levels are scaled up until tiles for higher zoom levels are loaded. (#5143)
  • Notification names and user info keys are now string enumeration values for ease of use in Swift. (#6794)
  • MGLMapDebugOverdrawVisualizationMask no longer has any effect in Release builds of the SDK. This debug mask has been disabled for performance reasons. (#5555)
  • Fixed a typo in the documentation for the MGLCompassDirectionFormatter class. (#5879)