How To Migrate/Switch From MapLibre Native iOS to MapTiler SDK Swift
This tutorial provides guidance on transitioning from MapLibre iOS to the MapTiler SDK Swift. If you currently use MapLibre’s iOS SDK, switching to MapTiler Swift is straightforward.
In most cases, you only need to replace the MapLibre dependency with the MapTiler SDK Swift, set the API key once via MTConfig.shared.setAPIKey, and swap MapLibre-specific classes/usages for the typed MapTiler SDK Swift APIs (MTMapView, MTMapOptions, MTMapReferenceStyle, MTMapViewContainer for SwiftUI, etc.). You’ll also replace style URLs containing ?key=… with strong-typed styles and optional language/terrain/globe/space options.
Next, see the main changes to migrate your app from MapLibre iOS to MapTiler Swift.
Installation
Replace the package dependency to use the MapTiler SDK Swift.
MapLibre iOS (Swift Package Manager)
// Xcode: File > Add Packages…
// URL: https://github.com/maplibre/maplibre-gl-native-distribution
// Package.swift example
dependencies: [
.package(url: "https://github.com/maplibre/maplibre-gl-native-distribution ", from: "X.Y.Z")
],
targets: [
.target(
name: "YourApp",
dependencies: ["MapLibre"]
)
]
MapTiler SDK Swift (Swift Package Manager)
// Xcode: File > Add Packages…
// URL: https://github.com/maptiler/maptiler-sdk-swift
// Product: MapTilerSDK
// Package.swift example
dependencies: [
.package(url: "https://github.com/maptiler/maptiler-sdk-swift ", from: "A.B.C") // use latest
],
targets: [
.target(
name: "YourApp",
dependencies: ["MapTilerSDK"]
)
]
// Set API key once (e.g., at app startup)
Task { await MTConfig.shared.setAPIKey("YOUR_API_KEY") }
Replace MapLibre Classes With MapTiler SDK Types
Search your app and replace MapLibre classes and helpers with MapTiler Swift equivalents. Some examples below.
MapLibre iOS (UIKit)
import MapLibre
import UIKit
class ViewController: UIViewController, MGLMapViewDelegate {
var mapView: MGLMapView!
override func viewDidLoad() {
super.viewDidLoad()
let styleURL = URL(string: "https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_API_KEY")!
mapView = MGLMapView(frame: view.bounds, styleURL: styleURL)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.delegate = self
view.addSubview(mapView)
}
}
MapTiler SDK Swift — SwiftUI
import SwiftUI
import CoreLocation
import MapTilerSDK
struct MyMapView: View {
@State private var mapView = MTMapView(
options: MTMapOptions(
center: CLLocationCoordinate2D(latitude: 47.3799, longitude: 8.5419),
zoom: 10.68
)
)
var body: some View {
MTMapViewContainer(map: mapView)
.referenceStyle(.streets)
.styleVariant(.defaultVariant)
}
}
MapTiler SDK Swift — UIKit
import UIKit
import CoreLocation
import MapTilerSDK
class ViewController: UIViewController, MTMapViewDelegate {
var mapView: MTMapView!
override func viewDidLoad() {
super.viewDidLoad()
let options = MTMapOptions(
center: CLLocationCoordinate2D(latitude: 47.3799, longitude: 8.5419),
zoom: 10.68
)
mapView = MTMapView(frame: view.bounds, options: options, referenceStyle: .streets)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.delegate = self
view.addSubview(mapView)
}
}
Migrate The Basemap Styles
Use MapTiler’s predefined styles without embedding ?key=… or hardcoding style versions.
MapLibre iOS
let styleUrl = URL(string: "https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_API_KEY")!
mapView.styleURL = styleUrl
MapTiler SDK Swift — SwiftUI
MTMapViewContainer(map: mapView)
.referenceStyle(.streets) // typed style, always latest
.styleVariant(.dark) // optional: .light/.pastel/etc.
MapTiler SDK Swift — UIKit
// Either pick reference style at init:
let mapView = MTMapView(frame: view.bounds, options: options, referenceStyle: .streets)
// Or set/change after initialization (e.g., in delegate didInitialize):
func mapViewDidInitialize(_ mapView: MTMapView) {
mapView.style?.setStyle(.streets, styleVariant: .dark)
}
//Optional: Language
// Set label language (e.g., device default or a specific country language)
await mapView.setLanguage(.special(.auto))
// or
// optional: .light/.pastel/etc.
Camera Animation
MapLibre iOS
// Move camera
let camera = MGLMapCamera(lookingAtCenter: nextCoord, altitude: 4500, pitch: 30, heading: 0)
mapView.setCamera(camera, animated: false)
// Animate camera
let animated = MGLMapCamera(lookingAtCenter: nextCoord, altitude: 4500, pitch: tilt, heading: bearing)
mapView.setCamera(animated, withDuration: 7.5, animationTimingFunction: CAMediaTimingFunction(name: .easeInEaseOut))
MapTiler SDK Swift
// Jump / Ease / Fly
await mapView.jumpTo(
nextCoord, options:
MTCameraOptions(
zoom: 11.0,
bearing: 0.0,
pitch: 30.0
)
)
await mapView.easeTo(
nextCoord,
options: MTCameraOptions(zoom: 12.0),
animationOptions: nil
)
let fly = MTFlyToOptions(curve: nil, minZoom: nil, speed: 0.5, screenSpeed: nil, maxDuration: nil)
await mapView.flyTo(
nextCoord,
options: fly,
animationOptions: nil
)
Add Sources and Layers
MapLibre iOS
let source = MGLShapeSource(identifier: "mySource", url: URL(string: "https://example.com/example.geojson")!, options: nil)
let line = MGLLineStyleLayer(identifier: "myLayer", source: source)
line.lineColor = NSExpression(forConstantValue: UIColor.red)
line.lineWidth = NSExpression(forConstantValue: 1.5)
if let style = mapView.style {
style.addSource(source)
style.addLayer(line)
}
MapTiler SDK Swift — SwiftUI
MTMapViewContainer(map: mapView) {
MTGeoJSONSource(identifier: "mySource", url: URL(string: "https://example.com/example.geojson")!)
MTLineLayer(identifier: "myLayer", sourceIdentifier: "mySource")
.color(.red)
.width(1.5)
}
.referenceStyle(.basic)
.styleVariant(.defaultVariant)
MapTiler SDK Swift — UIKit
let source = MTGeoJSONSource(identifier: "mySource", url: URL(string: "https://example.com/example.geojson")!)
let line = MTLineLayer(identifier: "myLayer", sourceIdentifier: source.identifier)
line.color = .red
line.width = 1.5
try await mapView.style?.addSource(source)
Custom Annotations
While MapLibre iOS uses MGLPointAnnotation and MGLAnnotationView for overlays, MapTiler SDK Swift provides MTMarker, MTTextPopup, and MTCustomAnnotationView for fully custom UIKit views.
import MapTilerSDK
import CoreLocation
import UIKit
final class MyCalloutView: MTCustomAnnotationView {
init(coord: CLLocationCoordinate2D) {
super.init(size: CGSize(width: 120, height: 48), coordinates: coord)
// Build your view hierarchy (add subviews, labels, etc.)
backgroundColor = .systemBackground
layer.cornerRadius = 8
}
required init?(coder: NSCoder) { super.init(coder: coder) }
}
// Add to map (after map initialized)
let callout = MyCalloutView(
coord: CLLocationCoordinate2D(latitude: 50.08804, longitude: 14.42076)
)
await callout.addTo(mapView)
For more info take a look at our custom annotations example.
Markers, Globe and Space
MapTiler SDK Swift also gives you options to change map projection to Globe, add space background behind it and annotate your data with markers.
SwiftUI
@State private var mapView = MTMapView(
options: MTMapOptions(
center: CLLocationCoordinate2D(latitude: 50.08804, longitude: 14.42076),
zoom: 3.2,
projection: .globe,
space: .config(MTSpace(preset: .milkywayColored))
)
)
var body: some View {
MTMapViewContainer(map: mapView)
.referenceStyle(.aquarelle)
.didInitialize {
Task {
await mapView.addMarker(MTMarker(coordinates: CLLocationCoordinate2D(latitude: 50.08804, longitude: 14.42076)))
}
}
}
UIKit
let options = MTMapOptions(
center: CLLocationCoordinate2D(latitude: 50.08804, longitude: 14.42076),
zoom: 3.2,
projection: .globe,
space: .config(MTSpace(preset: .milkywayColored))
)
let mapView = MTMapView(frame: view.bounds, options: options, referenceStyle: .aquarelle)
mapView.delegate = self
view.addSubview(mapView)
func mapViewDidInitialize(_ mapView: MTMapView) {
let pin = MTMarker(coordinates: CLLocationCoordinate2D(latitude: 50.08804, longitude: 14.42076))
mapView.addMarker(pin)
}
On this page