All docsMaps SDK for iOSGuidesAdding markers and shapes

Adding markers and shapes

You can use several approaches to add markers and shapes to a map. Each approach has different trade-offs. Below is an overview of the three main approaches with descriptions of their advantages and disadvantages and related resources for implementing each approach.

For a summary of features supported by each API, see the Compare use cases table, below.

For a high-level overview of visualizing point data with Mapbox, see our Add markers getting started guide.

Approach 1: Use annotations

Annotations provide an interface that will look familiar if you've used annotations in MapKit. It has built-in dragging and selection support. But using annotations is not recommended if you need to add a large number of markers to a map, or if you also need to style annotations differently based on a specific data property. If your project includes those requirements, consider using our more performant MGLStyleLayer classes, detailed below.

How annotations work

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 to change dynamically or be animated. For example, use this class if you need to show 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 markers, consider using more performant MGLStyleLayers instead, detailed below.

Examples

Below are screenshots of two examples using annotations.

MGLAnnotationImage
MGLAnnotationView

Related

Approach 2: Use 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. Using style layers requires that you implement your own gesture recognizers and callouts, but this approach is the most powerful option if you need to create rich map data visualizations within your app.

Try our Annotation Extension

If you want to implement style layers quickly, see our Annotation Extension (beta) below.

How style layers work

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.

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

To implement callouts with style layers, you 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.

Examples

Below are screenshots of two examples using style layers.

MGLCircleStyleLayer
MGLSymbolStyleLayer

The first example uses the MGLCircleStyleLayer class to display GeoJSON points as circle-shaped markers. Each circle has a unique color dependent on an attribute contained within the GeoJSON data.

The second example uses 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.

Related

Approach 3: Use the Annotation Extension

Beta

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

The Mapbox Annotation Extension for iOS combines 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.

Related

Compare use cases

See the table below for a summary of APIs that can be used to add shapes to a map. To see all columns in the table, scroll to the right.

Key

✅   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.