mapbox-android-patterns

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

android {
    defaultConfig {
        minSdk = 21
    }
}
 
dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
}

dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
    implementation("com.mapbox.extension:maps-compose:11.18.1")
}

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()
    ) {
        // Initialize camera via MapEffect (Style.STANDARD loads by default)
        MapEffect(Unit) { mapView ->
            // Set initial camera position
            mapView.mapboxMap.setCamera(
                CameraOptions.Builder()
                    .center(Point.fromLngLat(-122.4194, 37.7749))
                    .zoom(12.0)
                    .build()
            )
        }
    }
}

MapboxMap(
    modifier = Modifier.fillMaxSize(),
    scaleBar = {
        ScaleBar(
            enabled = true,
            position = Alignment.BottomStart
        )
    },
    compass = {
        Compass(enabled = true)
    }
) {
    // Style.STANDARD loads by default
}

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
 
    <com.mapbox.maps.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
 
</androidx.constraintlayout.widget.ConstraintLayout>

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()
    }
}

MapboxMap(modifier = Modifier.fillMaxSize()) {
    MapEffect(Unit) { mapView ->
        // Load style first
        mapView.mapboxMap.loadStyle(Style.STANDARD)
 
        // Create annotation manager and add markers
        val annotationManager = mapView.annotations.createPointAnnotationManager()
        val pointAnnotation = PointAnnotationOptions()
            .withPoint(Point.fromLngLat(-122.4194, 37.7749))
            .withIconImage("custom-marker")
        annotationManager.create(pointAnnotation)
    }
}
 
// Note: Compose doesn't have declarative PointAnnotation component
// Markers must be added imperatively via MapEffect

// Create annotation manager (once, reuse for updates)
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()
 
// Create marker
val pointAnnotation = PointAnnotationOptions()
    .withPoint(Point.fromLngLat(-122.4194, 37.7749))
    .withIconImage("custom-marker")
 
pointAnnotationManager.create(pointAnnotation)

val locations = listOf(
    Point.fromLngLat(-122.4194, 37.7749),
    Point.fromLngLat(-122.4094, 37.7849),
    Point.fromLngLat(-122.4294, 37.7649)
)
 
val annotations = locations.map { point ->
    PointAnnotationOptions()
        .withPoint(point)
        .withIconImage("marker")
}
 
pointAnnotationManager.create(annotations)

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

// Request permissions first (use ActivityResultContracts)
 
// Show location puck
mapView.location.updateSettings {
    enabled = true
    puckBearingEnabled = true
}

// Don't create new managers repeatedly
// val manager = mapView.annotations.createPointAnnotationManager() // each call
 
// Create once, reuse
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()
 
fun updateMarkers() {
    pointAnnotationManager.deleteAll()
    pointAnnotationManager.create(markers)
}

// Create all at once
pointAnnotationManager.create(allAnnotations)
 
// Don't create one by one in a loop

// 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()
}

// Standard style is optimized and recommended
Style.STANDARD
 
// Use other styles only when needed for specific use cases
Style.STANDARD_SATELLITE // Satellite imagery

mapView.mapboxMap.subscribeStyleLoaded { _ ->
    Log.d("Map", "Style loaded successfully")
    // Add layers and sources here
}