Working with the Jetpack Compose Extension

The Maps SDK for Android provides a Jetpack Compose Extension with individual guides covering specific use cases throughout this documentation site. But when you need to access Maps SDK features not covered by these guides or not exposed through the Compose Extension, you can use MapEffect to access the underlying MapView and its full API surface.

When to Use MapEffect

Use MapEffect when you need to:

• Access Maps SDK APIs not available in the Compose Extension
• Integrate with legacy code that uses MapView directly
• Implement advanced features requiring direct MapView manipulation

Use MapEffect with caution

Using MapView APIs within a MapEffect can introduce internal state changes that may conflict with Compose states, potentially leading to unexpected or undefined behavior. Always test thoroughly when mixing Compose state management with direct MapView API calls.

Example Usage

The following example shows how to enable debug features using MapEffect:

MainActivity.kt

package com.mapbox.maps.demo

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.maps.debugoptions.MapViewDebugOptions
import com.mapbox.maps.extension.compose.MapEffect
import com.mapbox.maps.extension.compose.MapboxMap

public class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContent {
      MapboxMap(modifier = Modifier.fillMaxSize()) {
        // Get reference to the raw MapView using MapEffect
        MapEffect(Unit) { mapView ->
          // Use mapView to access the Mapbox Maps APIs not in the Compose extension.
          // Changes inside `MapEffect` may conflict with Compose states.
          // For example, to enable debug mode:
          mapView.debugOptions = setOf(
            MapViewDebugOptions.TILE_BORDERS,
            MapViewDebugOptions.PARSE_STATUS,
            MapViewDebugOptions.TIMESTAMPS,
            MapViewDebugOptions.COLLISION,
            MapViewDebugOptions.STENCIL_CLIP,
            MapViewDebugOptions.DEPTH_BUFFER,
            MapViewDebugOptions.MODEL_BOUNDS,
            MapViewDebugOptions.TERRAIN_WIREFRAME,
          )
        }
      }
    }
  }
}

Was this page helpful?