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

# Interactions API

The new Interactions API is a toolset that allows you to handle interactions on layers, pre-defined [featuresets](https://docs.mapbox.com/style-spec/reference/featuresets/) in evolving basemap styles like Mapbox Standard, and the map itself. The API was introduced as experimental in Maps SDK `v11.9.0` and has been promoted to stable since `v11.13.0`.

To use the API, you define [`ClickInteraction`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-click-interaction/) or [`LongClickInteraction`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-long-click-interaction/) *interaction handlers* that target specific map layers, [featuresets](https://docs.mapbox.com/style-spec/reference/featuresets/), or the map itself. When a user interacts with map features belonging to one of these sets, the API will call the appropriate interaction handler for that feature that was clicked or long-clicked.

## Add an interaction to a map layer

Add interactions to the map by indicating the layer that should handle the interaction. The interaction will be triggered when a user clicks or long-clicks on a feature rendered on the specified layer. In Jetpack Compose, place the interactions inside the `MapboxMap` style using the appropriate interaction handler from [`styleInteractionsState`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.extension.compose.style.interactions/-style-interactions-state/) and in Android View applications, use [`mapboxMap.addInteraction()`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.plugin.delegates/-map-interaction-delegate/add-interaction.html) to add the interaction:

**Android View**

```kotlin

val token = mapboxMap.addInteraction(
  ClickInteraction.layer(id = "polygons") { feature, context ->
    // Handle tap when a feature from "polygons" is clicked.
    true // stops propagation
  }
)

// Cancel the token to remove the interaction. 
token.cancel()
```

**Jetpack Compose**

```kotlin

MapboxMap {
  ...
  style = GenericStyle(
    styleState = rememberStyleState {
      styleInteractionsState
        .onLayerClicked(id = "polygons") { feature, context ->
          // Handle tap when a feature from "polygons" is clicked.
          true // stops propagation
        }
    }
  )
}
```

The *interaction handlers* (`ClickInteraction`) in the examples above will be called each time a user taps a feature rendered on the `polygons` layer. The handler receives the feature that was clicked and the context containing information about the event.

You can add an interaction at any time, there is no need to wait for the style to load. If the interaction should be active as long as the `MapView` is alive, then the cancellation token can be omitted. If there is no layer with the name provided, then no interaction will be added.

## Add an interaction with featuresets

Interactions can be added not only to a layer, but also to a featureset. [Featuresets](https://docs.mapbox.com/style-spec/reference/featuresets/) are named groups of layers that can be defined in an evolving basemap style. In the [Mapbox Standard Style](https://docs.mapbox.com/api/maps/styles/#mapbox-standard), there are predefined Points-of-Interest (POI), Place Labels, and Buildings featuresets that include all appropriate features in the map. You can add interactions to your map that target these featuresets. Use the pre-defined [`StandardPoi`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-poi/), [`StandardPlaceLabels`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-place-labels/), and [`StandardBuildings`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-buildings/) featureset descriptors to enable interactions in the Standard Style.

**Android View**

```kotlin

mapboxMap.addInteraction(
  ClickInteraction.standardPoi { poi, context ->
    Log.d("Tap at poi:", poi.name!!)
    true
  }
)
```

**Jetpack Compose**

```kotlin

MapboxMap {
  ...
  style = MapboxStandardStyleExperimental(
    experimentalStandardStyleState = rememberExperimentalStandardStyleState {
      interactionsState.onPoiClicked { poi, context ->
        Log.d("Tap at poi:", poi.name!!)
        true
      }
    }
  )
}
```

When you use a predefined featureset, such as `.standardPoi`, the interaction will return a feature of a matching type (here a `StandardPoiFeature`). This means you will have access to properties specific to that feature type, such as `name` in the example above. To learn more about typed features that match the predefined featuresets, read the [`StandardPoiFeature`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-poi-feature/), [`StandardPlaceLabelsFeature`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-place-labels-feature/), and [`StandardBuildingsFeature`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-buildings-feature/) documentation.

## Set feature states

After a feature is returned from the interaction, you can set its [feature state](https://docs.mapbox.com/style-spec/reference/expressions/#feature-state). Setting the feature state allows you to control the appearance of individual features within a featureset.

For example, you may want to highlight individual buildings after a user clicks on them. To do this, you would add a `ClickInteraction` targeting the `.standardBuildings` featureset. When a user clicks on a building in this featureset, the building feature is returned as a `StandardBuildingsFeature`. You then set the feature state for this feature's `highlight` configuration option to `true`. By default, highlighted buildings will be displayed in blue, as shown in the image below. You can customize the color of highlighted buildings.

![Select buildings in the Mapbox Standard Style](https://docs.mapbox.com/android/ja/assets/ideal-img/maps-examples-pre-defined-feature-interaction.bd54275.480.png)

**Android View**

```kotlin

mapboxMap.addInteraction(
  ClickInteraction.standardBuildings { building, _ ->
    mapboxMap.setFeatureState(building, StandardBuildingsState {
      highlight(true)
    })
    true
  }
)
```

**Jetpack Compose**

```kotlin

MapboxMap {
  ...
  style = MapboxStandardStyleExperimental(
    experimentalStandardStyleState = rememberExperimentalStandardStyleState {
      interactionsState.onBuildingsClicked { building, _ ->
        building.setStandardBuildingsState {
          highlight(true)
        }
        true
      }
    }
  )
}
```

Each pre-defined featureset in the Standard Style has appropriate configuration options that can be modified at runtime in this way. Explore the [`StandardPoiState`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-poi-state/), [`StandardPlaceLabelsState`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-place-labels-state/) and [`StandardBuildingsState`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.interactions.standard.generated/-standard-buildings-state/) to learn more about the specific configuration options available for each featureset.

## Add an interaction to the map itself

You can add a special variant of the `Click` and `LongClick` interactions that doesn't take any layer or featureset as an argument. This lets you handle taps on the "map itself". This usually happens when user clicks a place on the map where there are no interactive features, or when the event propagated down to the map. `context` contains information about the interaction event, such as the point where the tap occurred.

**Android View**

```kotlin

mapboxMap.addInteraction(
  ClickInteraction { context ->
    Log.d("Click on map itself at:", context.screenCoordinate.toString())
    true
  }
)
mapboxMap.addInteraction(
  LongClickInteraction { context ->
    Log.d("Long click on map itself at:", context.screenCoordinate.toString())
    true
  }
)
```

**Jetpack Compose**

```kotlin

MapboxMap {
  ...
  style = GenericStyle(
    styleState = rememberStyleState {
      styleInteractionsState
        .onMapClicked { context ->
          Log.d("Click on map itself at:", context.screenCoordinate.toString())
          true
        }
        .onMapLongClicked { context ->
          Log.d("Long click on map itself at:", context.screenCoordinate.toString())
          true
        }
    }
  )
}
```

## Interactions order and propagation

In the map, there might be many features handling interactions. If a user taps at the point where multiple features are rendered, each of them can have a chance to handle the interaction. The Maps SDK will invoke each *interaction handler* (`ClickInteraction` or `LongClickInteraction`) one by one in the order that features are rendered. The top-most feature will be invoked first. So, if there are multiple interactions added to the same target (such as a layer and a featureset), the interactions added last will be called first.

By default, each *interaction handler* will completely handle the user interaction and stop propagation. If you want to continue propagating the interaction after the particular *interaction handler* is triggered, then return `false` in the callback.

## Examples

To learn more about working with the Interactions API, explore our examples using this API:

> **Related content (example): [Add interactions to predefined featuresets in Mapbox Standard](https://docs.mapbox.com/android/ja/maps/examples/compose/add-interaction-to-featuresets/)**
> 
> Jetpack Compose example that demonstrates how to add interactions to predefined featuresets in the Mapbox Standard Style.

> **Related content (example): [Add interactions to predefined featuresets in Mapbox Standard](https://docs.mapbox.com/android/ja/maps/examples/android-view/add-interaction-to-featuresets/)**
> 
> Android View example that demonstrates how to add interactions to predefined featuresets in the Mapbox Standard Style.

> **Related content (example): [Add interactions to custom featuresets and the map](https://docs.mapbox.com/android/ja/maps/examples/compose/add-interaction-to-custom-featuresets/)**
> 
> Jetpack Compose example that demonstrates how to add interactions to custom featuresets and the map itself.

> **Related content (example): [Add interactions to custom featuresets and the map](https://docs.mapbox.com/android/ja/maps/examples/android-view/add-interaction-to-custom-featuresets/)**
> 
> Android View example that demonstrates how to add interactions to custom featuresets and the map itself.