> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/maps/llms.txt)

# Annotations

Annotations are images or individually-styled circles, lines, or polygon features that are rendered above the map and fixed to specific geographic coordinates.

> **Note: Looking for a simpler option?**
> 
> If you're using SwiftUI and need pin-style markers, consider using **[Markers](https://docs.mapbox.com/ios/maps/guides/add-your-data/markers/)** instead. Markers provide a quick way to add default-styled markers without requiring custom image assets.

**Benefits:**

-   Available in both SwiftUI and UIKit
-   Built-in interaction support
-   No specific data format other than geographic coordinates (longitude and latitude)
-   Every annotation can be individually styled
-   Every annotation layer can be adjusted to be above or below another layer
-   Same performance benefits as using style layers

**Limitations:**

-   No default image available for point annotations (you must provide your own)
-   More complex setup compared to Markers
-   Inefficient for adding many features to the map

**SwiftUI**

In SwiftUI, add annotations to the map by including them in the `Map` block. Annotations conform to [`MapContent`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapcontent), which means they can be added directly to the map view. You can create and add individual instances of different annotation types, such as `PointAnnotation`, `CircleAnnotation`, `PolylineAnnotation`, and `PolygonAnnotation`.

**UIKit**

In UIKit, add annotations to the map with the [`MapView`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapview/)'s [`AnnotationOrchestrator`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/annotationorchestrator/). Use the `AnnotationOrchestrator` to create **annotation managers** based on the type of annotation that you're interested in. Every annotation manager handles a collection of annotations. Once a manager has been created, you can create and add individually styled instances of the corresponding annotation type.

## Point annotations

A [`PointAnnotation`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/pointannotation/) can display an image at any geographic coordinate. A common use case is to display a marker or pin representing a location that a user can tap on to get more information.

`PointAnnotation` works with any `UIImage`, so the compatible image formats include PNG, JPEG, GIF, TIFF, HEIC/HEIF, and PDF.

The Maps SDK for iOS does not provide a default image for point annotations. You must provide your own image asset. If you're using SwiftUI and need pin-style markers, consider using **[Markers](https://docs.mapbox.com/ios/maps/guides/add-your-data/markers/)** instead.

The code snippet below shows how to add a point annotation to the map using an image asset named `dest-pin`. You can download a PDF containing a red map marker to try out the `PointAnnotation` example.

[Download PDF](https://docs.mapbox.com/ios/ios/files/dest-pin.pdf)

**SwiftUI**

```swift
Map {
  let someCoordinate = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)
  PointAnnotation(coordinate: someCoordinate)
    .image(.init(image: UIImage(named: "dest-pin")!, name: "dest-pin"))
}
```

**UIKit**

```swift
// Initialize a point annotation with a New York City CLLocationCoordinate2D
let someCoordinate = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)
var pointAnnotation = PointAnnotation(coordinate: someCoordinate)

// Make the annotation show a red pin
pointAnnotation.image = .init(image: UIImage(named: "dest-pin")!, name: "dest-pin")

// Create the PointAnnotationManager, which will be responsible for handling this annotation
let pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

// Add the annotation to the manager in order to render it on the map.
pointAnnotationManager.annotations = [pointAnnotation]
```

> **Related content (example): [Add a marker to the map](https://docs.mapbox.com/ios/maps/examples/custom-point-annotation/)**
> 
> Use `MapView`'s `AnnotationOrchestrator` class to add a single red marker pin to the map using the Maps SDK for iOS.

![A screenshot of an iOS application displaying a map with a red marker pin in the center.](https://docs.mapbox.com/ios/assets/ideal-img/maps-examples-add-point-annotations.18d5cc7.480.png)

## Other shapes

`MapView`'s `AnnotationOrchestrator` also supports putting other shapes on the map including circles using [`CircleAnnotationManager`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/circleannotationmanager/), polylines using [`PolylineAnnotationManager`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/polylineannotationmanager/), and polygons using [`PolygonAnnotationManager`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/polygonannotationmanager/). These annotations work like the point annotations described above, but do not require an image. The options available for each type of annotation varies and you can find a full list in the API reference documentation.

### Circle annotation

A **circle annotation** ([`CircleAnnotation`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/circleannotation/)) places a circle at a point on the map.

**SwiftUI**

```swift
Map {
  let circleCoordinate = CLLocationCoordinate2DMake(40.7128, -74.0060)
  CircleAnnotation(centerCoordinate: circleCoordinate)
    .circleColor(.red)
}
```

**UIKit**

```swift
// Define a geographic coordinate.
let circleCoordinate = CLLocationCoordinate2DMake(40.7128, -74.0060)

// Create the circle annotation.
var circleAnnotation = CircleAnnotation(centerCoordinate: circleCoordinate)
circleAnnotation.circleColor = StyleColor(.red)

// Create the CircleAnnotationManager, which will be responsible for handling this annotation
let circleAnnotationManager = mapView.annotations.makeCircleAnnotationManager()

// Add the annotation to the manager.
circleAnnotationManager.annotations = [circleAnnotation]
```

> **Related content (example): [Add circle annotations](https://docs.mapbox.com/ios/maps/examples/circle-annotations/)**
> 
> To create the image below, use `MapView`'s `AnnotationOrchestrator` class to add many colored circles to the map using the Maps SDK for iOS.

![A screenshot of an iOS application showing circle annotations on a map.](https://docs.mapbox.com/ios/assets/ideal-img/maps-examples-circle-annotations.f5c73eb.480.png)

### Polyline annotation

A **polyline annotation** ([`PolylineAnnotation`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/polylineannotation/)) connects a list of coordinates on the map with a polyline. The order of the coordinates in the list will determine the order in which to connect the points, in the same way that coordinates are handled in the GeoJSON specification.

**SwiftUI**

```swift
Map {
  // Define two or more geographic coordinates to connect with a line.
  // Line from New York City, NY to Washington, D.C.
  let lineCoordinates = [
      CLLocationCoordinate2DMake(40.7128, -74.0060),
      CLLocationCoordinate2DMake(38.9072, -77.0369)
  ]

  PolylineAnnotation(lineCoordinates: lineCoordinates)
    .lineColor(.red)
}
```

**UIKit**

```swift
// Define two or more geographic coordinates to connect with a line.
// Line from New York City, NY to Washington, D.C.
let lineCoordinates = [
    CLLocationCoordinate2DMake(40.7128, -74.0060),
    CLLocationCoordinate2DMake(38.9072, -77.0369)
]
// Create the line annotation.
var lineAnnotation = PolylineAnnotation(lineCoordinates: lineCoordinates)
lineAnnotation.lineColor = StyleColor(.red)

// Create the PolylineAnnotationManager, which will be responsible for handling this annotation
let lineAnnotationManager = mapView.annotations.makePolylineAnnotationManager()

// Add the annotation to the manager.
lineAnnotationManager.annotations = [lineAnnotation]
```

> **Related content (example): [Add polyline annotations](https://docs.mapbox.com/ios/maps/examples/polyline-annotations/)**
> 
> To create the image below, use `MapView`'s `AnnotationOrchestrator` class to add many polylines to the map using the Maps SDK for iOS.

![A screenshot of an iOS application showing polyline annotations on a map.](https://docs.mapbox.com/ios/assets/ideal-img/maps-examples-add-polylines-annotations.aa3eb01.480.png)

### Polygon annotation

A **polygon annotation** ([`PolygonAnnotation`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/polygonannotation/)) takes a list of coordinates and will try to connect those coordinates and add the resulting polygonal shape to the map. The order of the coordinates in the list matters and works the same way as in the GeoJSON specification.

**SwiftUI**

```swift
Map {
  // Define three or more geographic coordinates to connect.
  let ring = Ring(coordinates: [
      CLLocationCoordinate2DMake(24.5171, -89.8571),
      CLLocationCoordinate2DMake(24.5171, -87.9675),
      CLLocationCoordinate2DMake(26.2441, -87.9675),
      CLLocationCoordinate2DMake(26.2441, -89.8571),
      CLLocationCoordinate2DMake(24.5171, -89.8571)
  ])

  PolygonAnnotation(polygon: Polygon(outerRing: ring))
}
```

**UIKit**

```swift
// Define three or more geographic coordinates to connect
  // Define a bounding box polygon over the center of the Gulf of Mexico
let ring = Ring(coordinates: [
    CLLocationCoordinate2DMake(24.5171, -89.8571),
    CLLocationCoordinate2DMake(24.5171, -87.9675),
    CLLocationCoordinate2DMake(26.2441, -87.9675),
    CLLocationCoordinate2DMake(26.2441, -89.8571),
    CLLocationCoordinate2DMake(24.5171, -89.8571)
])

// Create a new polygon annotation using those coordinates.
let polygonAnnotation = PolygonAnnotation(polygon: Polygon(outerRing: ring))

// Create the PolygonAnnotationManager, which will be responsible for handling this annotation
let polygonAnnotationManager = mapView.annotations.makePolygonAnnotationManager()

// Add the polygon to the map as an annotation.
polygonAnnotationManager.annotations = [polygonAnnotation]
```

> **Related content (example): [Add a polygon to the map](https://docs.mapbox.com/ios/maps/examples/polygon-annotation/)**
> 
> To create the image below, use `MapView`'s `AnnotationOrchestrator` class to add a single red polygon annotation to the map using the Maps SDK for iOS.

![A screenshot of an iOS application showing a red polygon annotation on a map.](https://docs.mapbox.com/ios/assets/ideal-img/maps-examples-polygon-annotation.25593e8.480.png)

## Interactivity

The [Map content gestures](https://docs.mapbox.com/ios/maps/guides/user-interaction/gestures/#map-content-gestures) allow you to assign Tap and Long Press gestures handlers to Annotations, Layers, and the Map. The handlers are called according to the rendered layer position starting from the top-most.

**SwiftUI**

```swift
Map {
  PolygonAnnotation(...)
    .onTapGesture { context in
      print("tapped point annotation at \(context.coordinate)")
      return true // Don't propagate the event to objects below
    }
}
  
```

**UIKit**

```swift
// Create an polygonAnnotationManager to handle polygon annotations
let annotationManager = mapView.annotations.makePolygonAnnotationManager()
var annotation = PolygonAnnotation(...)

// Add a tapHandler to the annotation, which will trigger when the annotation is tapped
annotation.tapHandler = { context in
  print("tapped point annotation at \(context.coordinate)")
  return true // Don't propagate the event to objects below
}

// Add the annotation to the annotation manager
annotationManager.annotations = [annotation]
```

## Removing Annotations

**SwiftUI**

When using SwiftUI, annotations and annotation groups conform to [`MapContent`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapcontent). Removing them from the `Map` block will also remove them from the map. This also works for conditional rendering. The code snippet below uses an `if` statement and a boolean state variable to control the visibility of a `PointAnnotation`.

```swift
@State var showAnnotation = false
Map {
    if showAnnotation {
        PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 12.4, longitude: -89.4))
              .image(named: "your-image-name")
    } 
}
```

**UIKit**

To remove an annotation, call `remove(at:)` or `removeAll()` on the annotation manager's annotations property.

```swift
// Create an circleAnnotationManager to handle circle annotations
let annotationManager = mapView.annotations.makeCircleAnnotationManager()

// Add a circle annotation
let circle = CircleAnnotation(...)
annotationManager.annotations.append(circle)

// Remove the circle annotation by its index
annotationManager.annotations.remove(at: 0)

// Remove the circle annotation by its id
annotationManager.annotations.removeAll { $0.id == circle.id }

// Remove all annotations managed by this annotation manager
annotationManager.annotations.removeAll()
```

To remove an annotation manager, call `mapView.annotations.removeAnnotationManager(withId:)`, passing the ID of the annotation manager that you want to remove. This removes the backing source and layer. The removed annotation manager will not be useful after it is removed.

An id can be specified when creating an annotation manager by passing an `id` parameter to the `makeXAnnotationManager(id:)` method. If no id is specified, a unique id will be generated automatically. You can retrieve the id of an existing annotation manager using its `id` property.

Annotation managers are removed implicitly if another annotation manager is created with the same ID.

```swift
// Create an polygonAnnotationManager to handle polygon annotations
let annotationManager = mapView.annotations.makePolygonAnnotationManager(id: "my-polygon-manager")

// add annotations to the manager

...

// Later, when you want to remove the annotation manager and its annotations
mapView.annotations.removeAnnotationManager(withId: "my-polygon-manager")
```