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.9.1. In your Gradle version catalog, add:

libs.versions.toml
[libraries]
maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "0.9.1" }

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.9.2-SNAPSHOT. In your Gradle version catalog, add:

libs.versions.toml
[libraries]
maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "0.9.2-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:

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

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
swiftPackageConfig {
  create("[cinteropName]") { 
    dependency {
      remotePackageVersion(
        url = URI("https://github.com/maplibre/maplibre-gl-native-distribution.git"),
        products = { add("MapLibre") },
        version = "6.15.0",
      )
    }
  }
}

Set up Vulkan on Android (Optional)

Warning

The Vulkan renderer is not yet as stable as the OpenGL renderer. Check the MapLibre Native issues for more info.

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

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

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

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

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

androidMain.dependencies {
  implementation(libs.maplibre.android.vulkan)
}

Set up Web (JS)

Warning

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

For Web, you'll additionally need to add the MapLibre CSS to your page. The easiest way to do this is via the CDN:

index.html
<!doctype html>
<html lang="en">
  <head>
    <link
      rel="stylesheet"
      href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css"
    />
    <title>Example Map</title>
  </head>
</html>

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 DATL4g/KCEF to embed a Chromium based browser. It requires some special configuration.

Add this Maven repo to your project:

settings.gradle.kts
repositories {
  maven("https://jogamp.org/deployment/maven")
}

Add these JVM flags to your app:

build.gradle.kts
compose.desktop {
  application {
    jvmArgs("--add-opens", "java.desktop/sun.awt=ALL-UNNAMED")
    jvmArgs(
      "--add-opens",
      "java.desktop/java.awt.peer=ALL-UNNAMED"
    ) // recommended but not necessary

    if (System.getProperty("os.name").contains("Mac")) {
      jvmArgs("--add-opens", "java.desktop/sun.lwawt=ALL-UNNAMED")
      jvmArgs("--add-opens", "java.desktop/sun.lwawt.macosx=ALL-UNNAMED")
    }
  }
}

Wrap your app with KcefProvider to download KCEF on first lanch, and MaplibreContext to provide the library with context about the window your app is running in:

Main.kt
fun main() {
  singleWindowApplication {
    KcefProvider(
      loading = { Text("Performing first time setup ...") },
      content = { MaplibreContextProvider { DemoApp() } },
    )
  }
}

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.