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" mapView.addAnnotation(annotation)
-mapView:annotationCanShowCallout: and similar methods for allowing interaction with a callout (example).
There are two basic ways to display the annotations you’ve added to a map, each with their own tradeoffs.
Annotation Images (
Annotation images are the quickest and most performant way to display annotations, but are also the most basic.
- The easiest way to display a marker on a map
- Easily customizable with any
- High performance, as the images are rendered directly in OpenGL
- Annotation images are purely static and cannot be animated
- No control over z-ordering
- Limits to the number and size of images you can add
Annotation Views (
If you’re looking to add custom
UIViews or have annotations that are dynamic or animatable, consider an
MGLAnnotationView instead of an
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
-mapView:viewForAnnotation and provide a custom
- Custom, native UIViews
- No limit on style or image size
- Full support for animations
- Relative control over z-ordering using the
- 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 of the other style feature subclasses to add points and shapes to an
From there, you can create one or many
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.visibleFeaturesAtPointto 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.