Skip to content

Getting started

This documentation assumes you already have a Compose Multiplatform project set up. If you haven't already, follow the official JetBrains documentation to set up a project.

Add the library to your app

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

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

libs.versions.toml
[libraries]
maplibre-compose = { module = "org.maplibre.compose:maplibre-compose", version = "0.13.0" }

Warning

The published documentation is for the latest release, and may not match the snapshot version. If using snapshots, always refer to the latest source code for the most accurate information.

First, follow GitHub's guide for authenticating to GitHub Packages. Your settings.gradle.kts should have something like this:

settings.gradle.kts
repositories {
  maven {
    url = uri("https://maven.pkg.github.com/maplibre/maplibre-compose")
    credentials {
      username = project.findProperty("gpr.user") as String? ?: System.getenv("GH_USERNAME")
      password = project.findProperty("gpr.key") as String? ?: System.getenv("GH_TOKEN")
    }
  }
}

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

libs.versions.toml
[libraries]
maplibre-compose = { module = "org.maplibre.compose:maplibre-compose", version = "0.13.1-SNAPSHOT" }

In your Gradle build script, add:

build.gradle.kts
commonMain.dependencies {
  implementation(libs.maplibre.compose)
}

Set up iOS

For iOS, you'll additionally need to add the MapLibre framework to your build. The easiest way is to select one of these two Gradle plugins:

Warning

In Xcode, ensure your Kotlin/Compose framework is linked before MapLibre.framework. Select your iOS app target, open Build Settings, search for Other Linker Flags, and order the flags like this:

-framework ComposeApp
-framework MapLibre

Replace ComposeApp with your Kotlin framework name. The opposite order can cause broken Compose text rendering on iOS because both Compose and MapLibre include HarfBuzz symbols.

See CMP-8882

Cocoapods

Info

CocoaPods will stop receiving new versions of packages in late 2026. See the official announcement.

Follow the official setup documentation, and add the below to include MapLibre in your build:

build.gradle.kts
cocoapods {
  pod("MapLibre", "6.25.1")
}

Swift Package Manager

Info

The MapLibre Compose repository uses this plugin for development, so a working example of this configuration can be found there.

Follow the official setup documentation, and add the below to include MapLibre in your build:

build.gradle.kts
kotlin {
  listOf(
    iosX64(),
    iosArm64(),
    iosSimulatorArm64()
  ).forEach { target ->
    target.swiftPackageConfig {
      dependency {
        remotePackageVersion(
          url = URI("https://github.com/maplibre/maplibre-gl-native-distribution.git"),
          products = { add("MapLibre", exportToKotlin = true) },
          packageName = "maplibre-gl-native-distribution",
          version = "6.25.1",
        )
      }
    }

    target.binaries.framework {
      baseName = "ComposeApp"
      isStatic = true
    }
  }
}

Revert to OpenGL on Android (Optional)

Warning

The OpenGL renderer is available for compatibility, but Vulkan is the default renderer for MapLibre Android 13 and later. Some Android emulators do not expose Vulkan support; use OpenGL when Vulkan initialization fails in an emulator.

By default, we ship with the standard version of MapLibre for Android, which uses the Vulkan backend. If you'd prefer to use the OpenGL backend, you can update your build.

First, add the OpenGL build of MapLibre to your version catalog:

libs.versions.toml
[libraries]
maplibre-android-opengl = { module = "org.maplibre.gl:android-sdk-opengl", version = "13.0.2" }

Then, exclude the standard MapLibre build from your dependency tree, and add the OpenGL build to your Android dependencies:

build.gradle.kts
commonMain.dependencies {
  implementation(libs.maplibre.compose.get().toString()) { // (1)!
    exclude(group = "org.maplibre.gl", module = "android-sdk")
  }
}

androidMain.dependencies {
  implementation(libs.maplibre.android.opengl)
}
  1. The .get().toString() is needed to work around a limitation in the Kotlin Gradle plugin.

Set up Web (JS)

Warning

Web support is not yet at feature parity with Android and iOS. Check the status table for more info.

There are no longer any special steps required to use MapLibre Compose on Web.

Set up Desktop (JVM)

Warning

Desktop support is not yet at feature parity with Android and iOS. Check the status table for more info.

On desktop, we use MapLibre Native via a JNI bindings module that bundles platform-specific native libraries. Add a runtime-only dependency for the platform you want to support, selecting exactly one capability matching your current OS/architecture combination.

build.gradle.kts
fun detectTarget(): String {
  val hostOs = when (val os = System.getProperty("os.name").lowercase()) {
    "mac os x" -> "macos"
    else -> os.split(" ").first()
  }
  val hostArch = when (val arch = System.getProperty("os.arch").lowercase()) {
    "x86_64" -> "amd64"
    "arm64" -> "aarch64"
    else -> arch
  }
  val renderer = when (hostOs) {
    "macos" -> "metal"
    else -> "opengl"
  }
  return "${hostOs}-${hostArch}-${renderer}"
}

sourceSets {
  val desktopMain by getting {
    dependencies {
      implementation(compose.desktop.currentOs)
      implementation("org.maplibre.compose:maplibre-compose:0.13.0")
      runtimeOnly("org.maplibre.compose:maplibre-native-bindings-jni:0.13.0") {
        capabilities {
          requireCapability("org.maplibre.compose:maplibre-native-bindings-jni-${detectTarget()}")
        }
      }
    }
  }
}

The following targets are available now:

  • macos-aarch64-metal
  • linux-amd64-opengl
  • linux-amd64-vulkan
  • windows-amd64-opengl
  • windows-amd64-vulkan

Other architectures and renderers will be added later.

Display your first map

In your Composable UI, add a map:

App.kt
@Composable
fun MyApp() {
  MaplibreMap()
}

When you run your app, you should see the default demotiles map. To learn how to get a detailed map with all the features you'd expect, proceed to Styling.