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)

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 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)
  • 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)

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)
  • 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)


  • MGLPolyline annotations and the exterior coordinates of MGLPolygon annotations are now able to be mutated, part or all, and changes are displayed immediately. (#6565)
  • 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)
  • 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)
  • Fixed an issue that could reset user-added transformations on annotation views. (#6166)
  • Fixed an issue that caused an annotation view to disappear if it isn’t created using the annotation view reuse queue. (#6485)
  • Deprecated -[MGLMapViewDelegate mapView:alphaForShapeAnnotation:] in favor of specifying an alpha component via -[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:] or -[MGLMapViewDelegate mapView:fillColorForPolygonAnnotation:]. (#6706)

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)
  • 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

  • As the user zooms in, tiles from lower zoom levels are scaled up until tiles for higher zoom levels are loaded. (#5143)
  • 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)