Getting started

This page assumes you have a Compose Multiplatform project. To create one, follow the official JetBrains documentation.

Add the library to your app

The library is published on Maven Central, and snapshot builds of main are additionally available from Central Portal Snapshots.

Releases (Maven Central)

The latest release is v0.15.0. In your Gradle version catalog, add:

libs.versions.toml

[libraries]
maplibre-compose = { module = "org.maplibre.compose:maplibre-compose", version = "0.15.0" }

Snapshots (Central Portal)

Caution

This site documents the latest release, which may not match the snapshot version. If using snapshots, read the documentation for the latest main instead.

Add the Central Portal Snapshots repository to your settings.gradle.kts:

settings.gradle.kts

repositories {
  maven {
    name = "Central Portal Snapshots"
    url = uri("https://central.sonatype.com/repository/maven-snapshots/")
    mavenContent { snapshotsOnly() }
    content {
      includeGroup("org.maplibre.compose")
      includeGroup("org.maplibre.nativeffi")
    }
  }
}

The latest snapshot is v0.15.1-SNAPSHOT. In your Gradle version catalog, add:

libs.versions.toml

[libraries]
maplibre-compose = { module = "org.maplibre.compose:maplibre-compose", version = "0.15.1-SNAPSHOT" }

In your Gradle build script, add:

build.gradle.kts

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

Use the same version for the library and for every runtime artifact below.

Configure your targets

Complete the section for each target that your app supports.

Android

Alongside the library, add a runtime for one render backend.

build.gradle.kts

androidMain {
  dependencies {
    runtimeOnly("org.maplibre.compose:maplibre-compose-runtime-vulkan-android:0.15.0")
  }
}

Available runtimes:

Render backend	Runtime
OpenGL	maplibre-compose-runtime-opengl-android
Vulkan	maplibre-compose-runtime-vulkan-android

iOS

The runtime’s system libraries link when Xcode links your app. Add them to your iOS app target’s Other Linker Flags build setting:

-l"c++"
-lz
-framework CoreFoundation
-framework CoreGraphics
-framework CoreText
-framework Foundation
-framework ImageIO
-framework Metal
-framework QuartzCore

Desktop (JVM)

Desktop requires Java 25. The native bindings use the FFM API, so the desktop target cannot run on an older JVM.

Alongside the library, add a runtime for your platform and one render backend.

build.gradle.kts

sourceSets {
  val jvmMain by getting {
    dependencies {
      implementation(compose.desktop.currentOs)
      implementation("org.maplibre.compose:maplibre-compose:0.15.0")

      // Linux x64 with Vulkan, for example.
      runtimeOnly("org.maplibre.compose:maplibre-compose-runtime-vulkan-linux-x64:0.15.0")
    }
  }
}

Available runtimes:

Platform	Runtime
Linux x64	maplibre-compose-runtime-vulkan-linux-x64
Linux arm64	maplibre-compose-runtime-vulkan-linux-arm64
macOS arm64	maplibre-compose-runtime-metal-macos-arm64
Windows x64	maplibre-compose-runtime-vulkan-windows-x64
Windows arm64	maplibre-compose-runtime-vulkan-windows-arm64

On desktop, a ComposeMapHost supplies the window’s graphics context. For Java AWT windows, use rememberAwtComposeMapHost. For an alternative Compose host, implement ComposeMapHost yourself.

Main.kt

fun main() {
  singleWindowApplication {
    ProvideMapHost(host = rememberAwtComposeMapHost(window)) {
      App()
    }
  }
}

The native bindings make FFM downcalls. Enable native access in your application configuration:

build.gradle.kts

compose.desktop {
  application {
    jvmArgs += "--enable-native-access=ALL-UNNAMED"
  }
}

Web (JS)

Compile the JS target to ES modules. Non-ESM builds are not supported.

build.gradle.kts

kotlin {
  js {
    useEsModules()
    browser()
  }
}

Configure MapLibre inside onWasmReady, before Compose starts. This is required to capture Compose’s graphics context.

main.kt

fun main() {
  onWasmReady {
    MapLibre.configure()
    ComposeViewport(document.body!!) { App() }
  }
}

Display your first map

In your Composable UI, add a map:

App.kt

@Composable
fun MyApp() {
  MaplibreMap()
}

When you run your app, the map shows the default demotiles style. To load a full-featured style, proceed to Styling.