Interacting with the map

Gestures and ornaments

Configuraton options for interaction vary significantly by platform. We provide some presets in common code, but if you're working with multiple platforms and you want to configure these in detail, you'll need to use expect/actual code.

map.common.kt

MaplibreMap(
  options =
    MapOptions(
      gestureOptions = GestureOptions.Standard,
      ornamentOptions = OrnamentOptions.OnlyLogo,
    )
)

Gestures

The map supports pan, zoom, rotate, and tilt gestures. Each of these can be enabled or disabled individually.

map.android.kt

MaplibreMap(
  options =
    MapOptions(
      gestureOptions =
        GestureOptions(
          isTiltEnabled = true,
          isZoomEnabled = true,
          isRotateEnabled = true,
          isScrollEnabled = true,
        )
    )
)

Ornaments

Info

We provide Material 3 alternatives to the default ornaments. See the Material 3 extensions section for more information.

Ornaments are built in UI elements that are displayed on the map, such as a compass or attribution button. You can control the visibility and position of these ornaments. They're implemented by the underlying MapLibre SDK, so may render differently on different platforms and the available options vary by platform.

map.android.kt

MaplibreMap(
  options =
    MapOptions(
      ornamentOptions =
        OrnamentOptions(
          padding = PaddingValues(0.dp), // (1)!
          isLogoEnabled = true, // (2)!
          logoAlignment = Alignment.BottomStart, // (3)!
          isAttributionEnabled = true, // (4)!
          attributionAlignment = Alignment.BottomEnd,
          isCompassEnabled = true, // (5)!
          compassAlignment = Alignment.TopEnd,
          isScaleBarEnabled = true, // (6)!
          scaleBarAlignment = Alignment.TopStart,
        )
    )
)

1. Insets the ornaments; useful if you have an edge-to-edge map or some UI elements that cover part of the map.
2. Displays a MapLibre logo
3. Possible alignments are constrained by the underlying SDK. The four corners are supported across platforms.
4. Displays attribution defined in the map style.
5. Displays a compass control when the map is rotated away from north.
6. Displays a scale control showing the distance represented by the map's zoom level.

Camera

If you want to read or mutate the camera state, use rememberCameraState(). You can use this to set the start position of the map:

val camera =
  rememberCameraState(
    firstPosition =
      CameraPosition(target = Position(latitude = 45.521, longitude = -122.675), zoom = 13.0)
  )
MaplibreMap(cameraState = camera)

You can now use the camera reference to move the camera. For example, CameraState exposes a suspend fun animateTo to animate the camera to a new position:

LaunchedEffect(Unit) {
  camera.animateTo(
    finalPosition =
      camera.position.copy(target = Position(latitude = 47.607, longitude = -122.342)),
    duration = 3.seconds,
  )
}

Click listeners

You can listen for clicks on the map. Given a click location, you can use camera state to query which features are present at that location:

MaplibreMap(
  cameraState = camera,
  onMapClick = { pos, offset ->
    val features = camera.projection?.queryRenderedFeatures(offset)
    if (!features.isNullOrEmpty()) {
      println("Clicked on ${features[0].json()}")
      ClickResult.Consume // (1)!
    } else {
      ClickResult.Pass
    }
  },
  onMapLongClick = { pos, offset ->
    println("Long click at $pos")
    ClickResult.Pass
  },
)

1. Consumes the click event, preventing it from propagating to the individual layers' click listeners.