Skip to main content

Using the Maps SDK for Android with Jetpack Compose

The Mapbox Maps SDK for Android offers a Jetpack Compose extension, enabling you to build map experiences using modern, declarative UI patterns. This extension acts as a wrapper around the main view-based Maps SDK, providing Compose-friendly APIs for the most common mapping use cases.

MapboxMap(
  Modifier.fillMaxSize(),
  mapViewportState = rememberMapViewportState {
    setCameraOptions {
      center(Point.fromLngLat(25.004, 60.239))
      zoom(9.0)
    }
  }
)
Not all SDK features are available via Jetpack Compose

Not all features of the Maps SDK are available through the Compose extension. Some advanced or less common APIs are only accessible via the traditional MapView and its associated classes. The Compose extension is designed to cover the majority of standard mapping scenarios, but if you need to access features not yet exposed, you can bridge the gap using MapEffect.

See the Using MapEffect for Advanced Features section of the guide for more details.

Use the Jetpack Compose extension if you want:

  • A modern, declarative approach to building map User Interfaces
  • Simplified integration with other Compose-based UI components
  • Access to the most common Maps SDK features with less boilerplate

Limitations:

  • Some advanced features and customizations are not yet available via Compose APIs
  • Direct access to the underlying MapView is possible, but requires caution (see MapEffect section)

For a full list of available APIs and up-to-date documentation, see the Jetpack Compose extension reference docs.

Installation​

To use the Jetpack Compose extension, add the appropriate dependency to your app's build.gradle file and enable Compose support:

android {
  // ...existing config...
  buildFeatures {
    compose = true
  }
}

dependencies {
  ...
  // If you're using compose also add the compose extension
  implementation("com.mapbox.extension:maps-compose-ndk27:11.17.1")
  // if your app does not require 16 KB page size support, the default dependency without -ndk27 can be used
  // implementation("com.mapbox.extension:maps-compose:11.17.1")
  ...
}

Refer to the main installation guide for full setup instructions, including how to get your Mapbox access token and configure your project.

Basic Usage Example​

Here's an example of displaying a Mapbox map using the Compose extension:

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.mapbox.geojson.Point
import com.mapbox.maps.extension.compose.MapboxMap
import com.mapbox.maps.extension.compose.animation.viewport.rememberMapViewportState

@Composable
public fun SimpleMap() {
  MapboxMap(
    Modifier.fillMaxSize(),
    mapViewportState = rememberMapViewportState {
      setCameraOptions {
        center(Point.fromLngLat(25.004, 60.239))
        zoom(9.0)
      }
    }
  )
}

You can further customize the map, add annotations, and respond to user gestures using additional Compose APIs. See the examples section for more advanced use cases.

Where to Find Mapbox Jetpack Compose Code Examples​

You can find a wide range of Jetpack Compose code snippets and real-world use cases throughout these docs.

Guides with Jetpack Compose code snippets​

These guides include Jetpack Compose code snippets to help you implement common mapping features:

Examples Using Jetpack Compose​

Examples demonstrating various features of the Maps SDK for Android using Jetpack Compose:

Browse the Compose examples directory for a comprehensive list of sample implementations. Clone and run the Jetpack Compose Examples App to see these examples in action.

Tutorials Using Jetpack Compose​

These step-by-step tutorials show you how to build specific features using Jetpack Compose:

Using MapEffect for Advanced Features​

MapEffect is a special composable that gives you direct access to the underlying MapView and its full API surface. Use it 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 or customizations not yet exposed via Compose APIs
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.

MapView APIs that should not be used with MapEffect​

Several plugins that work with MapView APIs are handled natively by the compose extension via Jetpack Compose APIs. These include:

  • mapView.lifecycle
  • mapView.compass
  • mapView.scalebar
  • mapView.logo
  • mapView.attribution

Accessing these APIs with the MapView from a MapEffect will result in a crash. Use the Jetpack Compose API counterparts instead.

Example: Enabling Debug Features​

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

MapboxMap(
  // ...other parameters...
) {
  MapEffect { mapView ->
    mapView.getMapboxMap().setDebug(true)
  }
}

More Examples Using MapEffect​

See these guides and examples for real-world usage of MapEffect:

Was this page helpful?