Skip to content

MapLibre Native





If you're building a native mobile application, MapLibre Native is the library you need. In this tutorial, we'll show you how to get a map in your existing application in as few steps as possible.

Before we get started though, you'll need a Stadia Maps API key. You can sign up for free, and no credit card is required! After signing up, create a property and create an API key (there's a button at the bottom of the page).

Get Started With a Free Account



On iOS, you can add the MapLibre package via the built-in Swift Package Manager. Apple provides general instructions in their documentation. The easiest way is to enter the package URL:; searching for the package does not always work.

Once added, all you have to do is add it to your view hierarchy. It works equally well in SwiftUI or plain old UIKit, though note that SwiftUI previews may be broken in some configurations due to a bug in Xcode.

// Import (at the top of your file)
import MapLibre

// Get this from somewhere else (see the warning at the top of the page)
let apiKey = "YOUR-API-KEY"

// You can find other styles in our library ( or
// provide your own (just make sure to include your API key in the source URL).
let styleID = "outdoors"

// Build the style url
let styleURL = URL(string: "\(styleID).json?api_key=\(apiKey)")

// create the mapview
let mapView = MLNMapView(frame: .zero, styleURL: styleURL)

Using SwiftUI?

If you're developing your app with SwiftUI and want a tighter integration with SwiftUI previews and a declarative DSL, check out our MapLibre SwiftUI DSL. We are still figuring out the best way to express certain APIs, so the interfaces may change ahead of a 1.0 release. We have also not fully modeled every possible underlying native data type and API, but what is there is working well. We are already using it in several internal projects and have a growing number of outside contributors who are aligned around the goal of making a high-quality SwiftUI DSL for MapLibre.


On Android, the MapLibre Native package is available from Maven Central. New Android Studio projects have this repository enabled by default. If it is not enabled, you can add mavenCentral() to your build script.

repositories {

Then, add MapLibre to your dependencies.

dependencies {
    implementation ''

You can now add a MapView in to your Activity's XML layout. Here is an example.


Finally, configure it in your Activity's onCreate method. Here is a minimal example.

override fun onCreate(savedInstanceState: Bundle?) {

    // Required SDK initialization before inflating/creating
    // the map view (MUST come before `setContentView` below)


    // Get this from somewhere else (see the warning at the top of the page)
    val apiKey = "YOUR-API-KEY"

    // You can find other styles in our library ( or
    // provide your own (just make sure to include your API key in the source URL).
    val styleId = "outdoors"

    // Build the style URL
    val styleUrl = "$styleId.json?api_key=$apiKey"

    // Create map view
    val mapView: MapView? = findViewById(
    mapView?.getMapAsync { map ->
        // This will be unnecessary in a future release, but for now it puts a
        // Mapbox logo in the corner, which is not necessary except when using Mapbox tiles.
        map.uiSettings.isLogoEnabled = false

        // Set the style after mapView was loaded
        map.setStyle(styleUrl) {
            // Add any extra initialization that requires
            // the style to be loaded here in a closure.

Using Jetpack Compose?

If you're developing your app with Jetpack Compose, check out Ramani Maps. This project is the spiritual twin of our SwiftUI DSL for the Android world. We've already contributed some improvements back to the project ourselves, and recommend taking a look if you're building a Compose app.

Next Steps

This example is just enough to get you started, but doesn't even scratch the surface of the rich APIs that MapLibre Native offers. For more information, refer to the official iOS and Android references.