User interaction

Additional Developer Resources

Users interacting with the Mapbox map in your application can explore the map by performing standard Android gestures on the touchscreen.

The Maps SDK includes the Mapbox Gestures for Android library for gesture detection based on user input. You can allow users to move the map using default gestures, enable and disable specific default gestures, or specify completely custom behavior for one or more gestures.

Note

The Mapbox Gestures for Android library wraps GestureDetectorCompat and ScaleGestureDetector. It also introduces implementations of rotate, move, shove, and tap gesture detectors.

Default map gestures

By default the following standard Android gestures will allow the user to explore the map:

Scroll around: Hold one finger down on the screen and move it in any direction.
Adjust pitch: Hold two fingers down on the screen and move them vertically across the screen.
Gradually zoom in/out: Pinch with two fingers to adjust the zoom level. Move fingers apart to zoom in, move fingers closer together to zoom out.
Rotate: Hold two fingers down on the screen and move them in a circular motion to rotate the map (adjust the bearing).
Zoom in one zoom level: Double tap on the screen with one finger to zoom in on the map's anchor point.
Zoom out one zoom level: Double tap on the screen with two fingers to zoom out with the map's anchor point centered.
Quick zoom: Double tap and drag up on the screen to zoom out, or double tap and drag down to zoom in.

The single tap gesture is used by the annotation managers to detect taps on annotations. You can add a target-action pair to this gesture recognizer to be notified when a single tap occurs on the map. For more details on annotation-related gestures, see the Markers and Annotations guide's Interactivity section.

PLAYGROUND

Location Helper

To experiment with camera pitch, bearing, tilt, and zoom and get values to use in your code, try our Location Helper tool.

Enable and disable default gestures

Adjust or completely disable scroll, rotate, pinch, and double tap gesture recognition by configuring GestureSettings.

Enable or disable default gestures

You can find a full list of gestures that can be enabled or disabled in the GestureSettings documentation. For example, to prevent users from changing the pitch of the map, set pitchEnabled to false:

Android View

Jetpack Compose

Android View

Jetpack Compose



mapView.gestures.pitchEnabled = false

Android View

Jetpack Compose


 
  mapState = rememberMapState{
 
    gesturesSettings = GesturesSettings { pitchEnabled = false }
 
  }

Note

Disabling map gestures doesn't affect whether you can change the camera position programmatically.

Configure scroll behavior

There are additional configuration options for scroll gestures.

Use scrollMode to configure the directions in which the map is allowed to move during a scroll gesture. By default, the map will move both horizontally and vertically.

Use scrollDecelerationEnabled to enable or disable the fling behavior after the scroll ends.

Configure pinch behavior

Configure pinch behavior using the following GestureSettings properties:

Listen for gesture events

The GesturesPlugin provides many gesture listeners. For example, you may want to listen for when the user rotates the map to print the bearing in degrees.

Android View

Jetpack Compose

Android View

Jetpack Compose



val rotateListener = object : OnRotateListener {
  override fun onRotateBegin(@NonNull detector: RotateGestureDetector) {
    // Do something when the user starts rotating the map.
  }

  override fun onRotate(@NonNull detector: RotateGestureDetector) {
    // Do something while the user rotates the map.
  }

  override fun onRotateEnd(@NonNull detector: RotateGestureDetector) {
    // Do something when the user stops rotating the map.
  }
}
gesturesPlugin.addOnRotateListener(rotateListener)

// Don't forget to remove the listener on onStop or onDestroy:
gesturesPlugin.removeOnRotateListener(rotateListener)

Android View

Jetpack Compose


 
  DisposableMapEffect(key1 = Unit) { mapView ->
 
    val rotateListener = object : OnRotateListener {
 
      override fun onRotateBegin(detector: RotateGestureDetector) {
 
        // Do something when the user starts rotating the map.
 
      }
 

 
      override fun onRotate(detector: RotateGestureDetector) {
 
        // Do something while the user rotates the map.
 
      }
 

 
      override fun onRotateEnd(detector: RotateGestureDetector) {
 
        // Do something when the user stops rotating the map.
 
      }
 
    }
 
    mapView.gestures.addOnRotateListener(rotateListener)
 
    onDispose {
 
      // remove the listener when the map leaves composition
 
      mapView.gestures.removeOnRotateListener(rotateListener)
 
    }
 
  }