Adding markers and shapes

There are several approaches that can be used to add markers and shapes to a map, each with different trade-offs. Below is an overview of the variety of approaches that can be used.

Using annotations

Any MGLPointAnnotation, MGLLine, or MGLPolygon that conforms to the MGLAnnotation protocol can be used to annotate the map to mark a place with a specific shape.

By implementing optional MGLMapViewDelegate, you can customize the basic styling of annotations. Commonly implemented delegate methods include:

  • -mapView:viewForAnnotation: returns an MGLAnnotationView that can associate a UIView with a specific MGLPointAnnotation.
  • -mapView:imageForAnnotation: returns an MGLAnnotationImage that can associate a UIImage with a specific MGLPointAnnotation.
  • -mapView:didSelectAnnotation: is called when an annotation is tapped on.
  • -mapView:annotationCanShowCallout: returns a boolean value indicating whether the annotation can display additional information inside a callout.
More about markers

Use the MGLAnnotationView class if you need your annotations change dynamically or be animated. For example, use this class if you need to showing user locations on a map using high-resolution profile pictures, or do complex animations as a result of user interaction. Using many MGLAnnotationViews can cause slow performance, so if you need to add a large number of annotations, consider using more performant MGLStyleLayers instead, detailed below.

In summary, using annotations provide a familiar interface to MapKit’s annotation implementation, with built-in dragging and selection support. But, it is not recommended if you need to add a large number of annotations to a map, or if you also need to style different annotations based on a specific data property - consider using our more performant MGLStyleLayer classes, detailed below.

MGLAnnotationImage
MGLAnnotationView

Using style layers

For full control of how shapes are displayed on a map, consider using style layers.

Style layers are more performant compared to UIView-based annotations. You will need to implement your own gesture recognizers and callouts, but it is the most powerful option if you need to create rich map data visualizations within your app.

Try out our Annotation Extension

If you want to get up and running with style layers quickly, see more information about our Annotation Extension for iOS (currently in beta) below.

Any MGLPointAnnotation, MGLLine, or MGLPolygon that is used in conjunction with an MGLStyleLayer class can be used to mark a place on a map with a specific shape.

They provide a deeply customizable interface and perform well when working with a large number of shapes.

To implement callouts style layers, you will need to create your own tap gesture recognizer that calls -[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:] to get the tapped point feature, then display a UIView you provide.

Below are two examples of using style layers.

MGLCircleStyleLayer
MGLSymbolStyleLayer

The first image makes use of the MGLCircleStyleLayer class to display GeoJSON points as circle-shaped markers. Each circle is has a unique color dependent on an attribute contained within the GeoJSON data.

The second image makes use of the MGLSymbolStyleLayer class to display a custom icon and text label associated with a point. Both the layout and styling of the icon and text are highly customizable.

Using the Annotation Extension (beta)

Public beta

The Mapbox Annotation Extension for iOS is in public beta, and is subject to changes.

The Annotation Extension is designed to combine the top benefits of annotations and style layers. It supports user interactions such as tapping, dragging, and displaying callouts, and enables full customization in the styling of shapes and symbols.

For more information about the Mapbox Annotation Extension for iOS, see the documentation.

Compare use cases

See the table below for a summary of APIs that can be used to add shapes to a map:

✅ Recommended

⚠️ Supported with caveats

➖ Unavailable or not supported

FeatureMGLAnnotationViewMGLAnnotationImageMGLSymbolStyleLayerMGLCircleStyleLayer
Customizability
Text labels, interactive subviews
⚠️
Static images only

Full support for text labels and label placement

Customize circle color and outline
Borrows familiar concepts fromMapKit, Google Maps SDKMapbox GL JS, Mapbox StudioMapbox GL JS, Mapbox Studio
Can use images


Can use text

Control Z-index
⚠️
Add multiple layers at, above, or below a specified layer index to control ordering
⚠️
Add multiple layers at, above, or below a specified layer index to control ordering
Drag and drop
Core Animation support
Add/move/replace

⚠️
Partial data updates are less performant than using annotations
⚠️
Partial data updates are less performant than using annotations
SceneKit support
Can be dynamically styled based on data attributes
Subclass
MGLPointAnnotation
to add custom attributes

Subclass
MGLPointAnnotation
to add custom attributes


Supports callouts
Built-in callouts included

Built-in callouts included
⚠️
Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts
⚠️
Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts
Supports clustering⚠️
Use a
third-party plugin


Still undecided on which approach will work for your use case? Reach out to our support team.

Was this page helpful?