Native Swift + Metal map rendering engine for SwiftUI apps.
Status: early alpha. The public API is not stable yet. Not production-ready. Not a drop-in replacement for Mapbox, MapLibre, or MapKit.
ImmersiveMap is an experimental native Swift + Metal map rendering engine for SwiftUI apps on Apple platforms. It is built for developers who need direct control over map rendering, custom vector tile providers, globe rendering, and native SwiftUI integration - without a WebView or a JavaScript bridge.
| Feature | Status |
|---|---|
| SwiftUI integration | Alpha |
| Native iOS (UIKit host) | Alpha |
| Native macOS (AppKit host, no Catalyst) | Alpha |
| Native Metal renderer | Alpha |
| Mapbox vector tiles | Alpha |
| OpenStreetMap / Shortbread provider | Alpha |
| Globe rendering | Alpha |
| Labels | Alpha |
| Avatars / live markers | Alpha |
| Disk / memory tile cache | Alpha |
| Offline maps | Planned |
| 3D Tiles | Planned |
| Stable public API | Not yet |
| Production readiness | Not yet |
- Swift 6.0+
- Xcode 16+
- iOS 18+
- macOS 15+ (native AppKit, not Mac Catalyst)
- Metal-capable device or simulator
ImmersiveMap is available on the Swift Package Index.
Add ImmersiveMap as a Swift Package dependency:
https://github.com/artembobkin/ImmersiveMap.git
Or in Xcode:
- Open your project.
- Select File → Add Package Dependencies…
- Paste the repository URL.
- Add the
ImmersiveMaplibrary to your app target.
import SwiftUI
import ImmersiveMap
struct ContentView: View {
@State private var camera = ImmersiveMapCameraController()
var body: some View {
ImmersiveMapView()
.cameraController(camera)
.enableCameraUIControls()
.ignoresSafeArea()
}
}ImmersiveMap ships with a built-in tile provider, so the snippet above renders a map out of the box - no token or account required. The same SwiftUI code runs natively on iOS (UIKit host) and macOS (AppKit host): ImmersiveMapView bridges to the platform view internally.
To use Mapbox vector tiles instead, attach a provider and style:
ImmersiveMapView()
.tileProvider(MapboxTileProvider(accessToken: "your-mapbox-public-token"))
.mapStyle(MapboxMapStyle())
// camera and other modifiers...The repository includes two host apps that reference the package locally:
ImmersiveMapIOS- iOS demo appImmersiveMapMac- native macOS demo app (AppKit, not Catalyst)
To run:
- Clone the repository.
- Open
ImmersiveMap.xcworkspace. - Select the
ImmersiveMapIOSorImmersiveMapMacscheme. - Add your Mapbox public token if you use the Mapbox provider (see the launch environment variables below).
- Build and run.
The host apps read optional launch environment variables: IMMERSIVE_MAP_TILE_BASE_URL, IMMERSIVE_MAP_AUTH_TOKEN, IMMERSIVE_MAP_MAPBOX_ACCESS_TOKEN, IMMERSIVE_MAP_MAPBOX_TILESET_ID. If the Mapbox token is present, the host apps use the Mapbox Vector Tiles API; otherwise they fall back to the OpenStreetMap / Shortbread provider.
See Documentation/docs/architecture.md.
- Early alpha; the public API may change.
- Not production-ready yet.
- Not a drop-in replacement for Mapbox, MapLibre, or MapKit.
- Currently focused on Apple platforms.
- Requires Metal.
- Tile provider terms and attribution are the responsibility of the app developer.
- Performance characteristics are still being measured.
See Documentation/docs/roadmap.md.
Run tests with Swift Package Manager:
swift testOr run the ImmersiveMapTests target from Xcode.
ImmersiveMap is MIT-licensed, but map tiles, styles, and geospatial datasets may have their own licenses and attribution requirements. When using Mapbox, OpenStreetMap, or other providers, make sure your app follows their terms and attribution rules.
ImmersiveMap is currently maintained as a single-maintainer experimental project. Issues and feedback are welcome. Pull requests are accepted for documentation, examples, bug fixes, and tests. See CONTRIBUTING.md.
ImmersiveMap is available under the MIT license. See LICENSE.
I am available for consulting and custom ImmersiveMap integrations.
Contact: @BobkinArtem