> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/ja/maps/llms.txt)

# Using the Maps SDK for Android with Jetpack Compose

The **Mapbox Maps SDK for Android** offers a [Jetpack Compose](https://developer.android.com/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.

```kotlin
MapboxMap(
  Modifier.fillMaxSize(),
  mapViewportState = rememberMapViewportState {
    setCameraOptions {
      center(Point.fromLngLat(25.004, 60.239))
      zoom(9.0)
    }
  }
)
```

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](#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](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.extension.compose/).

## Installation

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

```kotlin
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.28.0")
  // 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.28.0")
  ...
}
```

Refer to the [main installation guide](https://docs.mapbox.com/android/ja/maps/guides/install/) 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:

```kotlin
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](https://docs.mapbox.com/android/ja/maps/examples/compose/) 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:

-   [Set a style](https://docs.mapbox.com/android/ja/maps/guides/styles/set-a-style/)
-   [Styling layers with expressions](https://docs.mapbox.com/android/ja/maps/guides/styles/style-layers/)
-   [Work with sources and layers](https://docs.mapbox.com/android/ja/maps/guides/styles/work-with-layers/)
-   [Add annotations](https://docs.mapbox.com/android/ja/maps/guides/add-your-data/annotations/)
-   [Camera options and movement](https://docs.mapbox.com/android/ja/maps/guides/camera-and-animation/camera/)
-   [Camera animations](https://docs.mapbox.com/android/ja/maps/guides/camera-and-animation/animations/)
-   [Gestures](https://docs.mapbox.com/android/ja/maps/guides/user-interaction/gestures/)
-   [User interactions](https://docs.mapbox.com/android/ja/maps/guides/user-interaction/interactions/)

## Examples Using Jetpack Compose

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

-   [Display a Map](https://docs.mapbox.com/android/ja/maps/examples/compose/display-a-map)
-   [Add Point Annotations](https://docs.mapbox.com/android/ja/maps/examples/compose/add-point-annotations)
-   [Add Polygon Annotations](https://docs.mapbox.com/android/ja/maps/examples/compose/add-polygon-annotations)
-   [Add Polyline Annotations](https://docs.mapbox.com/android/ja/maps/examples/compose/add-polyline-annotations)
-   [Add Cluster Symbol Annotations](https://docs.mapbox.com/android/ja/maps/examples/compose/add-cluster-symbol-annotations)
-   [Location Component](https://docs.mapbox.com/android/ja/maps/examples/compose/location-component)
-   [Style States](https://docs.mapbox.com/android/ja/maps/examples/compose/style-states)
-   [Map Viewport Animation](https://docs.mapbox.com/android/ja/maps/examples/compose/map-viewport-animation)
-   [Simulate a Navigation Route](https://docs.mapbox.com/android/ja/maps/examples/compose/simulate-a-navigation-route)

Browse the [Compose examples directory](https://docs.mapbox.com/android/ja/maps/examples/compose/) for a comprehensive list of sample implementations. Clone and run the [Jetpack Compose Examples App](https://github.com/mapbox/mapbox-maps-android/tree/main/compose-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:

-   [Implement Geofencing in an Android App](https://docs.mapbox.com/help/tutorials/android-geofencing/)
-   [Add Interactions to your Map in Android](https://docs.mapbox.com/help/tutorials/android-interactions/)
-   [Add Location Search to an Android app](https://docs.mapbox.com/help/tutorials/android-location-search/)
-   [Build an Android marker app from a custom style and tileset](https://docs.mapbox.com/help/tutorials/android-marker-app-custom-style/)
-   [Build an Android marker app using GeoJSON data](https://docs.mapbox.com/help/tutorials/android-markers-from-geojson/)
-   [Use Offline Maps in an Android app](https://docs.mapbox.com/help/tutorials/android-offline-maps/)

## Using `MapEffect` for Advanced Features

[`MapEffect`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.extension.compose/-map-effect.html) 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

> **Note (warning): 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`:

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

### More Examples Using `MapEffect`

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

-   [Enable Debug Mode](https://docs.mapbox.com/android/ja/maps/examples/compose/debug-mode)
-   [Use an Image Source](https://docs.mapbox.com/android/ja/maps/examples/compose/use-an-image-source)