Getting started

This page assumes you have a Compose Multiplatform project. To create one, follow the official JetBrains documentation or run kotlin init compose-multiplatform.

Add the library

The library is published on Maven Central. The latest release is v0.15.0. Add it to the version catalog:

libs.versions.toml

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

Declare the dependency in the shared source set:

Gradle

build.gradle.kts

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

Kotlin Toolchain

shared/module.yaml

dependencies:
  - $libs.maplibre.compose

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

Snapshots

Snapshot builds of main are available from Central Portal Snapshots. This site documents the latest release, which may not match the snapshot. If you use snapshots, read the documentation for the latest main instead.

Add the snapshot repository, then set the catalog version to v0.15.1-SNAPSHOT.

Gradle

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")
    }
  }
}

Kotlin Toolchain

shared/module.yaml

repositories:
  - id: central-portal-snapshots
    url: https://central.sonatype.com/repository/maven-snapshots/

libs.versions.toml

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

Configure your targets

Complete the section for each target that your app supports.

Android

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

Gradle

build.gradle.kts

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

Kotlin Toolchain

android-app/module.yaml

dependencies:
  - //shared
  - org.maplibre.compose:maplibre-compose-runtime-vulkan-android:0.15.0:
      scope: runtime-only

Available runtimes:

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

Both Android runtimes support armeabi-v7a, arm64-v8a, and x86_64.

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.

Gradle

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")
    }
  }
}

Kotlin Toolchain

Caution

Use Gradle for the desktop target. Kotlin Toolchain 0.12.0 cannot fetch the native runtime.

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 ComposeMapPresentationHost supplies the window’s graphics context. For Java AWT windows, use rememberAwtComposeMapPresentationHost. For an alternative Compose host, implement ComposeMapPresentationHost yourself.

Main.kt

fun main() {
  singleWindowApplication {
    ProvideMapPresentationHost(host = rememberAwtComposeMapPresentationHost(window)) {
      App()
    }
  }
}

The native bindings make FFM downcalls. Enable native access when you run the app:

Gradle

build.gradle.kts

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

Kotlin Toolchain

Caution

Use Gradle for the desktop target. Kotlin Toolchain 0.12.0 cannot fetch the native runtime.

Web (JS)

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

Gradle

build.gradle.kts

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

Kotlin Toolchain

shared/module.yaml

product:
  type: kmp/lib
  platforms: [jvm, android, iosArm64, iosSimulatorArm64, js]

js-app/module.yaml

product: js/app

dependencies:
  - //shared

Install the browser graphics integration inside onWasmReady, before Compose starts. The integration captures Compose’s graphics context.

main.kt

fun main() {
  onWasmReady {
    installMapLibreCompose()
    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.