MapLibre Native¶

Free

Starter

Standard

Professional

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.

Get Started With a Free Account

Quickstart¶

iOS¶

SwiftUIUIKit

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 (1)
    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)
    }    
}

Learn how to get an API key in our authentication guide.

Check out the documentation on the Swift Package Index to learn more. The SwiftUI DSL also has a directory full of examples on GitHub.

In case you need some feature from MapLibre Native that isn't in the SwiftUI DSL yet, the MapView has an unsafeMapViewControllerModifier(_:) extension method. This gives you raw access to the underlying MLNMapView, so your important work won't be blocked by a missing API.

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 (1)
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)

Learn how to get an API key in our authentication guide.

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 (1)
    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.
        }
    }
}

Learn how to get an API key in our authentication guide.

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.