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.6.0. In your Gradle version catalog, add:
[libraries]
maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "0.6.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:
repositories {
maven {
url = uri("https://maven.pkg.github.com/sargunv/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.6.1-SNAPSHOT. In your Gradle version catalog, add:
[libraries]
maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "0.6.1-SNAPSHOT" }
In your Gradle build script, add:
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 to do this in Kotlin Multiplatform is with the CocoaPods Gradle plugin:
cocoapods {
pod("MapLibre", "6.9.0")
}
Set up Vulkan on Android (Optional)¶
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:
[libraries]
maplibre-android-vulkan = { module = "org.maplibre.gl:android-sdk-vulkan", version = "11.7.1" }
Then, exclude the standard MapLibre build from your dependency tree, and add the Vulkan build to your Android dependencies:
commonMain.dependencies {
implementation(libs.maplibre.compose) {
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:
<!doctype html>
<html lang="en">
<head>
<link rel='stylesheet' href='https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css'/>
</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:
repositories {
maven("https://jogamp.org/deployment/maven")
}
Add these JVM flags to your app:
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:
fun main() {
singleWindowApplication {
KcefProvider(
loading = { Text("Performing first time setup ...") },
content = { MaplibreContextProvider { DemoApp() } },
)
}
}
Display your first map¶
In your Composable UI, add a map:
@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.