# Adding markers and shapes

> **Note (legacy): 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.29.0, in the [Maps SDK documentation](https://docs.mapbox.com/ios/maps/guides/markers-and-annotations/).

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](https://docs.mapbox.com/ios/legacy/maps/guides/markers-and-annotations/#compare-use-cases) table, below.

For a high-level overview of visualizing point data with Mapbox, see our [Add markers](https://docs.mapbox.com/help/getting-started/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.

> **Note: 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 `MGLAnnotationView`s can cause slow performance, so if you need to add a large number of markers, consider using more performant `MGLStyleLayer`s instead, detailed below.

### Examples

Below are screenshots of two examples using annotations.

![](https://docs.mapbox.com/ios/assets/ideal-img/maps-overivew-annotation-image.6bc9e39.480.png)

MGLAnnotationImage

![](https://docs.mapbox.com/ios/assets/ideal-img/maps-overview-annotation-view.b0849af.480.png)

MGLAnnotationView

**Related**

-   Reference: [Mapbox Maps SDK for iOS: Annotations](https://docs.mapbox.com/ios/maps/api/6.4.1/Annotations.html)
-   Example: [Add a marker symbol](https://docs.mapbox.com/ios/legacy/maps/examples/add-marker-symbol/) - *Uses `MGLPointAnnotation`*
-   Example: [Annotation views](https://docs.mapbox.com/ios/legacy/maps/examples/annotation-views/) - *Uses `MGLAnnotationView`*

## Approach 2: Use style layers

For full control of how shapes are displayed on a map, consider using [style layers](https://docs.mapbox.com/ios/legacy/maps/guides/runtime-styling/).

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.

> **Note: Try our Annotation Extension**
> 
> If you want to implement style layers quickly, see our [Annotation Extension](#approach-3-use-the-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:]`](https://docs.mapbox.com/ios/maps/api/6.4.1/Classes/MGLMapView.html#/c:objc(cs)MGLMapView(im)visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:) to get the tapped point feature, then display a `UIView` you provide.

### Examples

Below are screenshots of two examples using style layers.

![](https://docs.mapbox.com/ios/assets/ideal-img/maps-overview-circle-layer.10ef436.480.png)

MGLCircleStyleLayer

![](https://docs.mapbox.com/ios/assets/ideal-img/maps-overview-symbol-layer.3127c40.480.png)

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**

-   Reference: [Mapbox Maps SDK for iOS: Style Layers](https://docs.mapbox.com/ios/maps/api/6.4.1/Style%20Layers.html)
-   Example: [Add a line style layer from GeoJSON](https://docs.mapbox.com/ios/legacy/maps/examples/runtime-add-line/) - *Uses `MGLStyleLayer`*

## Approach 3: Use the Annotation Extension

> **Note (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](https://docs.mapbox.com/ios/annotation-extension/api/0.0.1-beta.1/).

**Related**

-   Repository: [Mapbox Annotation Extension for iOS](https://github.com/mapbox/mapbox-annotation-extension)
-   Blog: [Quickly add annotations to mobile maps: Introducing the new iOS Annotation Extension](https://medium.com/mapbox/quickly-add-annotations-to-mobile-maps-e59710d640d2)

## 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](https://github.com/hulab/ClusterKit/) \| ➖ \| ✅  
\| ✅  
\|

Still undecided on which approach will work for your use case? [Reach out to our support team](https://support.mapbox.com/).