MapLibre for Compose

This project is a Compose Multiplatform library for MapLibre. You can use it to embed an interactive vector map in your Compose app.

Android and iOS support is implemented with MapLibre Native.

Desktop and Web are not yet supported.

Usage

This library is published via Maven Central, and snapshot builds of main are additionally available on GitHub Packages.

In your Gradle version catalog, add:

[libraries]
# ...
maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "0.1.0" }

In your Gradle build script, add:

commonMain.dependencies {
  // ...
  implementation(libs.maplibre.compose)
}

For iOS, you'll additionally need to add the MapLibre framework to your build. The easiest way to do this in Kotlin Multiplatform is with the CocoaPods Gradle plugin:

cocoapods {
  // ...
  pod("MapLibre", "6.8.1")
}

In your app's UI, add a map:

@Composable
fun MyMapScreen() {
  MaplibreMap()
}

For full usage information, see the demo app and docs.

Status

Many common use cases are already supported, but the full breadth of the MapLibre SDKs is not yet covered. What is already supported may have bugs. API stability is not yet guaranteed; as we're still exploring how best to express an interactive map API in Compose.

The following is currently supported:

• Instantiate an interactive map in Compose UI
• Load a map style via URL, including
  • Remote (online) styles
  • Local asset styles with Compose resources
• Configure the map UI, including:
  • Position ornaments (compass, logo, attribution) with Compose PaddingValues and alignment
  • Toggle map gestures
• Position or animate the camera and read its state
• Dynamically reload the style (say, to switch themes)
• Add custom layers to the map with a declarative Composable API, including:
  • Injecting layers in between base style layers (say, to render underneath labels)
  • Defining GeoJSON sources via URL or Spatial K geometry
  • Defining raster and vector sources via URL
  • Defining background, circle, fill, extrusion, heatmap, hillshade, line, raster, and symbol layers
  • Configuring layers with expressions
  • onClick and onLongClick callbacks with data on which map feature was tapped
• Replace base style layers, with all the same functionality above

The following is not yet supported, but planned:

• Add annotations
• Show user location
• Bound the camera
• Show a scale bar
• Configure transitions for transitionable properties
• Convert between screen space and world space coordinates
• Query the map for visible features
• Dynamically configure style properties beyond just sources/layers
• Configure the offline cache
• Interact with base style layers
• Snapshot maps

The following may be explored in the future:

• Support desktop and/or web
• Support for secondary platforms (car?, watch?, tv?)
• Expose map style as mutable state for advanced use cases
• Improve type safety for expressions
• Depend on the MapLibre Native core directly instead of the Android/IOS SDKs
• Re-implement camera gestures in Compose and fully hoist camera state
• Decouple composable style management from map rendering, for use in style generation scripts

Contributions are welcome for any of the above!