Labsco
mapbox logo

mapbox-android-patterns

★ 68

by mapbox · part of mapbox/mapbox-agent-skills

Official integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and…

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#git#maps
🧩 One of 7 skills in the mapbox/mapbox-agent-skills package — works on its own, and pairs well with its siblings.

Official integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by mapbox

Official integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and… npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-android-patterns Download ZIPGitHub68

Mapbox Android Integration Patterns

Official patterns for integrating Mapbox Maps SDK v11 on Android with Kotlin, Jetpack Compose, and View system.

Use this skill when:

  • Installing and configuring Mapbox Maps SDK for Android

  • 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:

Map Initialization

Jetpack Compose Pattern

Basic map:

Copy & paste — that's it
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()
 )
 }
 }
}

With ornaments:

Copy & paste — that's it
MapboxMap(
 modifier = Modifier.fillMaxSize(),
 scaleBar = {
 ScaleBar(
 enabled = true,
 position = Alignment.BottomStart
 )
 },
 compass = {
 Compass(enabled = true)
 }
) {
 // Style.STANDARD loads by default
}

View System Pattern

Layout XML (activity_map.xml):

Copy & paste — that's it

Activity:

Copy & paste — that's it
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()
 }
}

Add Markers (Point Annotations)

Point annotations are the most common way to mark locations on the map.

Jetpack Compose:

Copy & paste — that's it
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

View System:

Copy & paste — that's it
// 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)

Multiple markers:

Copy & paste — that's it
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)

Show User Location (Display)

Step 1: Add permissions to AndroidManifest.xml:

Copy & paste — that's it

Step 2: Request permissions and show location:

Copy & paste — that's it
// Request permissions first (use ActivityResultContracts)

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

Performance Best Practices

Reuse Annotation Managers

Copy & paste — that's it
// 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)
}

Batch Annotation Updates

Copy & paste — that's it
// Create all at once
pointAnnotationManager.create(allAnnotations)

// Don't create one by one in a loop

Lifecycle Management

Copy & paste — that's it
// 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

Copy & paste — that's it
// Standard style is optimized and recommended
Style.STANDARD

// Use other styles only when needed for specific use cases
Style.STANDARD_SATELLITE // Satellite imagery

Reference Files

Load these references when you need detailed patterns for specific topics:

  • references/compose.md -- Jetpack Compose: dependencies, token setup, MapboxMap, annotations with click, GeoJSON, MapEffect

  • references/annotations.md -- Circle, Polyline, and Polygon annotation patterns

  • references/location-tracking.md -- Camera follow user location + get current location once

  • references/custom-data.md -- GeoJSON sources and layers: lines, polygons, points, update/remove

  • references/camera-styles.md -- Camera control (set, animate, fit) + map styles (built-in and custom)

  • references/interactions.md -- Featureset interactions, custom layer taps, long press, gestures

Additional Resources