How To Migrate/Switch From MapBox iOS SDK to MapTiler SDK Swift
This tutorial provides guidance on transitioning from Mapbox iOS to the MapTiler SDK Swift. If you currently use Mapbox’s iOS SDK, switching to MapTiler Swift is straightforward.
In most cases, you only need to replace the Mapbox dependency with the MapTiler SDK Swift, set the API key once via MTConfig.shared.setAPIKey, and swap Mapbox-specific classes/usages for the typed MapTiler SDK Swift APIs (MTMapView, MTMapOptions, MTMapReferenceStyle, MTMapViewContainer for SwiftUI, etc.). You’ll also replace style URIs/URLs or custom style IDs with strong-typed styles and optional language/terrain/globe/space options.
Next, see the main changes to migrate your app from Mapbox iOS to MapTiler Swift.
Installation
Replace the package dependency to use the MapTiler SDK Swift.
Mapbox iOS SDK (Swift Package Manager)
// Xcode: File > Add Packages…
// URL: https://github.com/mapbox/mapbox-maps-ios
// Package.swift example
dependencies: [
.package(url: "https://github.com/mapbox/mapbox-maps-ios.git", from: "X.Y.Z")
],
targets: [
.target(
name: "YourApp",
dependencies: ["Mapbox"]
)
]
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 Mapbox Classes With MapTiler SDK Types
Search your app and replace Mapbox classes and helpers with MapTiler Swift equivalents. Some examples below.
MapBox iOS SDK (UIKit)
import UIKit
import MapboxMaps
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let mapView = MapView(frame: view.bounds)
let cameraOptions = CameraOptions(center:
CLLocationCoordinate2D(latitude: 47.3799, longitude: 8.5419),
zoom: 10.68, bearing: 0, pitch: 0)
mapView.mapboxMap.setCamera(to: cameraOptions)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
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.
MapBox iOS SDK
mapView = MapView(
frame: view.bounds,
mapInitOptions: MapInitOptions(styleURI: .standard))
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
MapBox iOS SDK
Map(initialViewport: .camera(
center: nextCoord,
zoom: 11.0,
bearing: 0.0,
pitch: 30.0
))
mapView.camera.fly(to: nextCoord, duration: 12)
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
MapBox iOS SDK
var body: some View {
Map {
GeoJSONSource(id: "mySource")
.data(.url(URL(string: "https://example.com/example.geojson")!))
LineLayer(id: "myLayer", source: "mySource")
.fillOpacity(0.9)
}
}
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 MapBox iOS uses annotations API 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