Skip to content

MapLibre Native

Free

Starter

Standard

Professional

MapLibre Native lets you add snappy, interactive maps to your mobile apps. While there are several other libraries available, MapLibre is our recommended choice for high-performance interactive vector maps. In this tutorial, we'll show you how to get a map in your existing app in as few steps as possible.

Before we get started, 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.

Get Started With a Free Account

Quickstart

iOS

MapLibre Native integrates easily into SwiftUI with the MapLibre SwiftUI DSL. To get started, add the Swift Package dependency to your project. The repo URL is https://github.com/maplibre/swiftui-dsl.

Fun fact

The MapLibre SwiftUI DSL started as an internal project at Stadia Maps, and is now officially part of the MapLibre ecosystem!

Here's a quick example to get started:

import MapLibre
import MapLibreSwiftUI
import MapLibreSwiftDSL
import SwiftUI

public struct MyView {
    // Be sure to store this securely 
    let apiKey = "YOUR-API-KEY"

    // You can find other styles in our library (https://docs.stadiamaps.com/themes/) or
    // provide your own.
    let styleID = "outdoors"

    // Build the style URL
    let styleURL = URL(string: "https://tiles.stadiamaps.com/styles/\(styleID).json?api_key=\(apiKey)")

    // A collection of points with various attributes.
    let pointSource = ShapeSource(identifier: "points") {
        // Uses the DSL to quickly construct point features inline
        MLNPointFeature(coordinate: CLLocationCoordinate2D(latitude: 51.47778, longitude: -0.00139))

        MLNPointFeature(coordinate: CLLocationCoordinate2D(latitude: 0, longitude: 0)) { feature in
            feature.attributes["heading"] = 45
        }

        MLNPointFeature(coordinate: CLLocationCoordinate2D(latitude: 39.02001, longitude: 1.482148)) { feature in
            feature.attributes["heading"] = 145
        }
    }

    @State var camera = MapViewCamera.center(
        CLLocationCoordinate2D(latitude: 48.2082, longitude: 16.3719),
        zoom: 5,
        direction: 0
    )

    public var body: some View {
        MapView(styleURL: styleURL) {
            // Symbol layer demonstration with an icon rendered for each point.
            // The rotation is dynamically selected from the attributes associtaed with each point feature.
            // Note that we can reference the layer directly using the DSL!
            // No more string ID references are needed in most use cases!
            SymbolStyleLayer(identifier: "rotated-symbols", source: pointSource)
                .iconImage(UIImage(systemName: "location.north.circle.fill")!)
                .iconRotation(featurePropertyNamed: "heading")
        }
        .ignoresSafeArea(.all)
    }    
}

Not bad for just a few lines of code! Take the next step and learn how this all works, explore dynamic styling, marker clustering and more in our interactive markers tutorial.

Want to skip straight to the reference? Then the documentation on the Swift Package Index to learn more.

And last but not least, the SwiftUI DSL also has a directory full of examples on GitHub.

Building a UIKit-based app? You can add the MapLibre package directly via the built-in Swift Package Manager. The easiest way is to enter the package URL: https://github.com/maplibre/maplibre-gl-native-distribution; searching for the package does not always work. Here's a skeleton to get you started.

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

// Be sure to store this securely 
let apiKey = "YOUR-API-KEY"

// You can find other styles in our library (https://docs.stadiamaps.com/themes/) or
// provide your own.
let styleID = "outdoors"

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

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

From here, we recommend checking out the official MapLibre iOS Documentation, which is also full of example snippets!

Android

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.

build.gradle
repositories {
    mavenCentral()
}

Then, add MapLibre to your dependencies.

build.gradle
dependencies {
    implementation 'org.maplibre.gl:android-sdk:10.2.0'
}

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

<com.mapbox.mapboxsdk.maps.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

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

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

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

    setContentView(R.layout.activity_main)

    // Be sure to store this securely 
    val apiKey = "YOUR-API-KEY"

    // You can find other styles in our library (https://docs.stadiamaps.com/themes/) 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 = "https://tiles.stadiamaps.com/styles/$styleId.json?api_key=$apiKey"

    // Create map view
    val mapView: MapView? = findViewById(R.id.mapView)
    mapView?.onCreate(savedInstanceState)
    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.