Imported from AgentCorp-Inc/AgentCorp-Integrations-Skills (Mapbox/skills/mapbox-android-patterns/AGENTS.md). Install upstream with npx skills add AgentCorp-Inc/AgentCorp-Integrations-Skills --skill mapbox-android-patterns. Copyright stays with the author.

Mapbox Android Quick Reference

Fast reference for Mapbox Maps SDK v11 on Android with Kotlin, Jetpack Compose, and View system.

Setup

Installation (Gradle)

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
        }
    }
}

// build.gradle.kts
dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
    implementation("com.mapbox.extension:maps-compose:11.18.1") // For Compose
}

Access Token

<!-- app/res/values/mapbox_access_token.xml -->
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false"
        tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string>
</resources>

Jetpack Compose

Basic Map

import androidx.compose.runtime.*
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.maps.extension.compose.*
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

@Composable
fun MapScreen() {
    MapboxMap(modifier = Modifier.fillMaxSize()) {
        MapEffect(Unit) { mapView ->
            mapView.mapboxMap.setCamera(
                CameraOptions.Builder()
                    .center(Point.fromLngLat(-122.4194, 37.7749))
                    .zoom(12.0)
                    .build()
            )
        }
    }
}

With Annotation

MapboxMap(modifier = Modifier.fillMaxSize()) {
    MapEffect(Unit) { mapView ->
        val annotationManager = mapView.annotations.createPointAnnotationManager()
        val pointAnnotation = PointAnnotationOptions()
            .withPoint(Point.fromLngLat(-122.4194, 37.7749))
            .withIconImage("marker")
        annotationManager.create(pointAnnotation)
    }
}

Compose Annotations Pattern

// ❌ Declarative annotation components are not supported
// Use MapEffect with annotation managers instead (see above)
MapboxMap(modifier = Modifier.fillMaxSize()) {
    // This doesn't work:
    PointAnnotation(
        point = Point.fromLngLat(-122.4194, 37.7749)
    ) {
        iconImage = "custom-marker"
    }
}

View System

Basic Map

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.mapbox.maps.MapView
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

class MapActivity : AppCompatActivity() {
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_map)

        mapView = findViewById(R.id.mapView)

        mapView.mapboxMap.setCamera(
            CameraOptions.Builder()
                .center(Point.fromLngLat(-122.4194, 37.7749))
                .zoom(12.0)
                .build()
        )

        mapView.mapboxMap.loadStyle(Style.STANDARD)
    }

    override fun onStart() {
        super.onStart()
        mapView.onStart()
    }

    override fun onStop() {
        super.onStop()
        mapView.onStop()
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.onDestroy()
    }
}

Common Patterns

1. Add Markers

val manager = mapView.annotations.createPointAnnotationManager()

val annotation = PointAnnotationOptions()
    .withPoint(Point.fromLngLat(-122.4194, 37.7749))
    .withIconImage("custom-marker")

manager.create(annotation)

2. User Location with Camera Follow

// Request permission (add to AndroidManifest.xml)
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

// Show user location
mapView.location.updateSettings {
    enabled = true
    puckBearingEnabled = true
}

// Follow user location with camera
mapView.location.addOnIndicatorPositionChangedListener { point ->
    mapView.camera.easeTo(
        CameraOptions.Builder()
            .center(point)
            .zoom(15.0)
            .pitch(45.0)
            .build(),
        MapAnimationOptions.Builder()
            .duration(1000)
            .build()
    )
}

// Optional: Follow bearing (direction)
mapView.location.addOnIndicatorBearingChangedListener { bearing ->
    mapView.camera.easeTo(
        CameraOptions.Builder()
            .bearing(bearing)
            .build(),
        MapAnimationOptions.Builder()
            .duration(1000)
            .build()
    )
}

3. Add Custom Data (GeoJSON)

val geoJsonSource = geoJsonSource("route-source") {
    geometry(LineString.fromLngLats(coordinates))
}
mapView.mapboxMap.style?.addSource(geoJsonSource)

val lineLayer = lineLayer("route-layer", "route-source") {
    lineColor(Color.BLUE)
    lineWidth(4.0)
}
mapView.mapboxMap.style?.addLayer(lineLayer)

4. Camera Control

// Fly animation
mapView.camera.flyTo(
    CameraOptions.Builder()
        .center(destination)
        .zoom(15.0)
        .build(),
    MapAnimationOptions.Builder()
        .duration(2000)
        .build()
)

// Ease animation
mapView.camera.easeTo(
    CameraOptions.Builder()
        .center(destination)
        .zoom(15.0)
        .build(),
    MapAnimationOptions.Builder()
        .duration(1000)
        .build()
)

5. Featureset Interactions

import com.mapbox.maps.interactions.ClickInteraction

// Tap on POI features
mapView.mapboxMap.addInteraction(
    ClickInteraction.standardPoi { poi, context ->
        Log.d("MapTap", "Tapped POI: ${poi.name}")
        true // Stop propagation
    }
)

// Tap on buildings
mapView.mapboxMap.addInteraction(
    ClickInteraction.standardBuildings { building, context ->
        Log.d("MapTap", "Tapped building")
        // Highlight the building
        mapView.mapboxMap.setFeatureState(
            building,
            StandardBuildingsState {
                highlight(true)
            }
        )
        true
    }
)

6. Map Tap Handling

mapView.gestures.addOnMapClickListener { point ->
    Log.d("MapClick", "Tapped at: ${point.latitude()}, ${point.longitude()}")
    true // Consume event
}

7. Styles

// Compose
MapboxMap(style = Style.STANDARD)  // Recommended
MapboxMap(style = Style.DARK)
MapboxMap(style = Style.STANDARD_SATELLITE)

// Views
mapView.mapboxMap.loadStyle(Style.STANDARD)
mapView.mapboxMap.loadStyle(Style.DARK)

Performance Tips

Reuse Managers

// ✅ Create once
val annotationManager = mapView.annotations.createPointAnnotationManager()

// ✅ Update many times
fun updateMarkers() {
    annotationManager.deleteAll()
    annotationManager.create(newMarkers)
}

Batch Updates

// ✅ Create all at once
pointAnnotationManager.create(allAnnotations)

// ❌ Don't create one by one
allAnnotations.forEach { annotation ->
    pointAnnotationManager.create(annotation)
}

Lifecycle Management

// Always call lifecycle methods
override fun onStart() {
    super.onStart()
    mapView.onStart()
}

override fun onStop() {
    super.onStop()
    mapView.onStop()
}

override fun onDestroy() {
    super.onDestroy()
    mapView.onDestroy()
}

Use Standard Style

// ✅ Recommended
Style.STANDARD

// Use others only when needed
Style.STANDARD_SATELLITE

Quick Checklist

✅ Token in mapbox_access_token.xml ✅ Maven repository configured ✅ MapboxMaps dependency added ✅ Location permissions if needed ✅ Use Style.STANDARD (recommended) ✅ Lifecycle methods called ✅ Annotation managers reused

Resources

• Android Maps Guides
• API Reference
• Interactions Guide
• Jetpack Compose Guide
• Examples