Skip to main content

Adding markers and shapes

Additional Developer Resources
A newer version of the Maps SDK is available

This page uses v6.4.1 of the Mapbox Maps SDK. A newer version of the SDK is available. Learn about the latest version, v11.9.0, in the Maps SDK documentation.

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

| Feature | MGLAnnotationView | MGLAnnotationImage | MGLSymbolStyleLayer | MGLCircleStyleLayer | |---|---|---|---|---| | Customizability | ✅
Text labels, interactive subviews | ⚠️


Static images only | ✅
Full support for text labels and label placement | ✅
Customize circle color and outline | | Borrows familiar concepts from | MapKit, Google Maps SDK | ➖ | Mapbox GL JS, Mapbox Studio | Mapbox 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.

Additional Developer Resources