Adding Points to a Map

Mapbox offers a few different ways to add points to a map, each with different tradeoffs.


It’s straightforward to add an annotation to a map. You can use MGLPointAnnotation as is, or you can subclass it to add annotations with richer data.

let annotation = MGLPointAnnotation()
annotation.coordinate = CLLocationCoordinate2D(latitude: 45.5076, longitude: -122.6736)
annotation.title = "Bobby's Coffee"
annotation.subtitle = "Coffeeshop"

See the MGLMapViewDelegate method -mapView:annotationCanShowCallout: and similar methods for allowing interaction with a callout (example).

Displaying annotations

There are two basic ways to display the annotations you’ve added to a map, each with their own tradeoffs.

Annotation Images (MGLAnnotationImage)

Annotation images are the quickest and most performant way to display annotations, but are also the most basic.

By default, annotations added to the map are displayed with a red pin (example). To use custom images, you can implement MGLMapViewDelegate -mapView:imageForAnnotation: (example).


  • The easiest way to display a marker on a map
  • Easily customizable with any UIImage
  • High performance, as the images are rendered directly in OpenGL


  • Annotation images are purely static and cannot be animated
  • No control over z-ordering

Annotation Views (MGLAnnotationView)

If you’re looking to add custom UIViews or have annotations that are dynamic or animatable, consider an MGLAnnotationView instead of an MGLAnnotationImage (example).

Annotation views have significant advantages over annotation images when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures.

To use annotation views, implement MGLMapViewDelegate -mapView:viewForAnnotation and provide a custom MGLAnnotationView (UIView) subclass.


  • Custom, native UIViews
  • No limit on style or image size
  • Full support for animations
  • Relative control over z-ordering using the zPosition property on CALayer
  • Familiar API for MapKit users


  • Performance implications:
    • UIViews are inherently slow to render compared to OpenGL, more apparent if you’re adding many views or moving the map rapidly
    • In some cases, you might consider runtime styling

Advanced: Runtime Styling

For absolute full control of how points are displayed on a map, consider runtime styling.

You can use MGLPointFeature or any other style primitives to add points and shapes to an MGLShapeSource.

From there, you can create one or many MGLSymbolStyleLayer or MGLCircleStyleLayer layers to filter and style points for display on the map (example).


  • Most powerful option
  • Highest performance (rendered in GL directly)
  • SDK-level support for labels rendered together with icons
  • Finer control of z-ordering
    • Rendering respects ordering within the data source
    • Otherwise layers are lightweight so you can create a new layer for each level you need


  • Currently you must implement your own tap gesture recognizer together with MGLMapView.visibleFeaturesAtPoint to recognize taps and manually show callouts (example).
  • Currently no SDK support for animations. If you need animations, consider using an NSTimer and updating the layer properties accordingly.