Mapbox Android Patterns

by mapboxaab3a6fef5c6No licenseListed Oct 8, 2026Updated Oct 8, 2026

Official integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and featureset interactions. Based on official Mapbox documentation.

Instructions onlySoftware Development

AI-generated overview

Reference patterns for integrating the Mapbox Maps SDK v11 into Android apps with Kotlin, Jetpack Compose, and the View system.

What it does: Provides integration guidance and code patterns for the Mapbox Maps SDK v11 on Android, covering installation, access token and manifest setup, map initialization, markers and annotations, user location display, custom GeoJSON data, styles, camera control, and feature interactions. It also lists performance practices and troubleshooting steps. Reference files hold deeper patterns for Compose, annotations, location tracking, custom data, camera and styles, and interactions.
When to use it: Use when building or maintaining an Android app that embeds Mapbox maps and you need concrete setup or usage patterns. Also useful for adding markers, showing user location, loading custom data, or handling map taps and gestures.
Requirements: Android SDK 21+, Kotlin or Java, Android Studio, and a Mapbox account with an access token. The app needs the Mapbox Maven repository, the com.mapbox.maps:android dependency (and maps-compose for Compose), and the INTERNET permission; location features also need location permissions. Instructions only, no scripts.

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:

Installation & Setup

Requirements

Android SDK 21+
Kotlin or Java
Android Studio
Free Mapbox account

Step 1: Configure Access Token

Create app/res/values/mapbox_access_token.xml:

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>

<?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>

Get your token: Sign in at mapbox.com

Step 1b: Internet permission (required)

Maps need network access. Include this in AndroidManifest.xml — agents often omit it and only list location permissions later:

Step 2: Add Maven Repository

In settings.gradle.kts:

kotlin

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

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

Step 3: Add Dependency

In module build.gradle.kts:

kotlin

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

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

For Jetpack Compose:

kotlin

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

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

Map Initialization

Jetpack Compose Pattern

Basic map:

kotlin

import androidx.compose.runtime.*import androidx.compose.foundation.layout.fillMaxSizeimport androidx.compose.ui.Modifierimport com.mapbox.maps.extension.compose.*import com.mapbox.maps.Styleimport com.mapbox.geojson.Point
@Composablefun 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()            )        }    }}

import androidx.compose.runtime.*import androidx.compose.foundation.layout.fillMaxSizeimport androidx.compose.ui.Modifierimport com.mapbox.maps.extension.compose.*import com.mapbox.maps.Styleimport com.mapbox.geojson.Point
@Composablefun 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:

kotlin

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

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

xml

<?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>

<?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>

Activity:

kotlin

import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport com.mapbox.maps.MapViewimport com.mapbox.maps.Styleimport 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()    }}

import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport com.mapbox.maps.MapViewimport com.mapbox.maps.Styleimport 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:

kotlin

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

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:

kotlin

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

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

Multiple markers:

kotlin

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)

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:

xml

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

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

Step 2: Request permissions and show location:

kotlin

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

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

Performance Best Practices

Reuse Annotation Managers

kotlin

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

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

Batch Annotation Updates

kotlin

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

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

Lifecycle Management

kotlin

// Always call lifecycle methodsoverride fun onStart() {    super.onStart()    mapView.onStart()}
override fun onStop() {    super.onStop()    mapView.onStop()}
override fun onDestroy() {    super.onDestroy()    mapView.onDestroy()}

// Always call lifecycle methodsoverride fun onStart() {    super.onStart()    mapView.onStart()}
override fun onStop() {    super.onStop()    mapView.onStop()}
override fun onDestroy() {    super.onDestroy()    mapView.onDestroy()}

Use Standard Style

kotlin

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

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

Troubleshooting

Map Not Displaying

Check:

Token in mapbox_access_token.xml
Token is valid (test at mapbox.com)
Maven repository configured
Dependency added correctly
Internet permission in manifest

Style Not Loading

kotlin

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

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

Performance Issues

Use Style.STANDARD (recommended and optimized)
Limit visible annotations to viewport
Reuse annotation managers
Avoid frequent style reloads
Call lifecycle methods (onStart, onStop, onDestroy)
Batch annotation updates

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

Source and attribution

Source:mapbox/mapbox-agent-skillsinskills/mapbox-android-patternsat commitaab3a6f

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Mapbox Android Patterns

Mapbox Android Integration Patterns

Installation & Setup

Requirements

Step 1: Configure Access Token

Step 1b: Internet permission (required)

Step 2: Add Maven Repository

Step 3: Add Dependency

Map Initialization

Jetpack Compose Pattern

View System Pattern

Add Markers (Point Annotations)

Show User Location (Display)

Performance Best Practices

Reuse Annotation Managers

Batch Annotation Updates

Lifecycle Management

Use Standard Style

Troubleshooting

Map Not Displaying

Style Not Loading

Performance Issues

Reference Files

Additional Resources

Source and attribution

More from mapbox/mapbox-agent-skills

Mapbox Web Performance Patterns

Mapbox Style Quality

Mapbox Mcp Devkit Patterns

Mapbox Location Grounding

Mapbox Ios Patterns

Mapbox Geospatial Operations

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api