Mapbox iOS Patterns

Mapbox iOS Integration Patterns

Official patterns for integrating Mapbox Maps SDK v11 on iOS with Swift, SwiftUI, and UIKit.

Use this skill when:

• Installing and configuring Mapbox Maps SDK for iOS
• Adding markers and annotations to maps
• Showing user location and tracking with camera
• Adding custom data (GeoJSON) to maps
• Working with map styles, camera, or user interaction
• Handling feature interactions and taps

Official Resources:

• iOS Maps Guides
• API Reference
• Example Apps

Installation & Setup

Requirements

• iOS 14+
• Xcode 15+
• Swift 5.9+
• Free Mapbox account

Step 1: Configure Access Token

Add your public token to Info.plist:

<key>MBXAccessToken</key>
<string>pk.your_mapbox_token_here</string>

Get your token: Sign in at mapbox.com

Step 2: Add Swift Package Dependency

1. File → Add Package Dependencies
2. Enter URL: https://github.com/mapbox/mapbox-maps-ios.git
3. Version: "Up to Next Major" from 11.0.0
4. Verify four dependencies appear: MapboxCommon, MapboxCoreMaps, MapboxMaps, Turf

Alternative: CocoaPods or direct download (install guide)

Map Initialization

SwiftUI Pattern

Basic map:

import SwiftUI
import MapboxMaps

struct ContentView: View {
    @State private var viewport: Viewport = .camera(
        center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
        zoom: 12
    )

    var body: some View {
        Map(viewport: $viewport)
            .mapStyle(.standard)
    }
}

With ornaments:

Map(viewport: $viewport)
    .mapStyle(.standard)
    .ornamentOptions(OrnamentOptions(
        scaleBar: .init(visibility: .visible),
        compass: .init(visibility: .adaptive),
        logo: .init(position: .bottomLeading)
    ))

UIKit Pattern

import UIKit
import MapboxMaps

class MapViewController: UIViewController {
    private var mapView: MapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let options = MapInitOptions(
            cameraOptions: CameraOptions(
                center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
                zoom: 12
            )
        )

        mapView = MapView(frame: view.bounds, mapInitOptions: options)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)

        mapView.mapboxMap.loadStyle(.standard)
    }
}

Add Markers

The SDK offers three ways to place a point on the map. Pick the simplest one that fits.

Agent note: A SwiftUI Mapbox sketch is incomplete without at least one annotation (Marker, PointAnnotation, or MapViewAnnotation). Do not ship a bare Map { } with no pin.

Which API should I use?

For hundreds or thousands of features, use a style layer (SymbolLayer on a GeoJSONSource) instead of annotations.

Markers API (recommended for simple cases, SwiftUI)

import SwiftUI
@_spi(Experimental) import MapboxMaps

struct ContentView: View {
    var body: some View {
        Map {
            Marker(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
                .color(.red)
                .text("San Francisco")
        }
    }
}

Multiple markers from a collection:

Map {
    ForEvery(locations, id: \.id) { location in
        Marker(coordinate: location.coordinate)
            .color(.red)
            .text(location.name)
    }
}

Scaling note. Marker and PointAnnotation each create their own view or symbol entry per pin — fine up to about 100 markers. For larger datasets (hundreds or thousands of features — common with open-ended GeoJSON feeds), load the data into a GeoJSONSource and render it with a SymbolLayer instead. That scales to thousands of features and enables clustering.

PointAnnotation (custom image)

SwiftUI:

Map(viewport: $viewport) {
    PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
        .image(.init(image: UIImage(named: "marker")!, name: "marker"))
}

UIKit:

// Create annotation manager (once, reuse for updates)
var pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

// Create marker
var annotation = PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
annotation.iconAnchor = .bottom

// Add to map
pointAnnotationManager.annotations = [annotation]

Multiple markers:

let annotations = locations.map { coordinate in
    var annotation = PointAnnotation(coordinate: coordinate)
    annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
    return annotation
}

pointAnnotationManager.annotations = annotations

Show User Location

Step 1: Add location permission to Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Show your location on the map</string>

Step 2: Request permissions and show location:

import CoreLocation

// Request permissions
let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()

// Show user location puck
mapView.location.options.puckType = .puck2D()
mapView.location.options.puckBearingEnabled = true

Performance Best Practices

Reuse Annotation Managers

// ❌ Don't create new managers repeatedly
func updateMarkers() {
    let manager = mapView.annotations.makePointAnnotationManager()
    manager.annotations = markers
}

// ✅ Create once, reuse
let pointAnnotationManager: PointAnnotationManager

init() {
    pointAnnotationManager = mapView.annotations.makePointAnnotationManager()
}

func updateMarkers() {
    pointAnnotationManager.annotations = markers
}

Batch Annotation Updates