Getting started

ImmersiveMap is a map for SwiftUI apps on iOS and macOS: a globe that unrolls into a flat map, with buildings, relief, your own data and 3D models. This page takes you from adding the package to the first map on screen.

Adding the package

In Xcode, choose File > Add Package Dependencies and enter:

https://github.com/artembobkin/ImmersiveMap.git

Add the ImmersiveMap library to your app’s target. The map runs on iOS 18 and macOS 15 with Xcode 16.3 or later. The package compiles its Metal shaders with a build plugin, so Xcode asks you to trust the plugin on the first build. On the command line, pass -skipPackagePluginValidation to xcodebuild.

On macOS, allow the network. A new Mac app in Xcode is sandboxed, and the sandbox blocks the tile downloads. The map then shows the stars, the atmosphere and the badge around a black globe, with no error. Turn on Outgoing Connections (Client) under Signing & Capabilities → App Sandbox. A map that reads its tiles from a file in the bundle needs no network (see Setting up the tile source).

The first map

import SwiftUI
import ImmersiveMap

struct ContentView: View {
    var body: some View {
        ImmersiveMapView()
            .ignoresSafeArea()
    }
}

This is the whole planet from the hosted tiles, with the built-in style, the globe at low zooms, buildings with detailed models of the landmarks (see 3D content), trees and the attribution badge. Nothing needs a key or an account.

Modifiers

Everything about the map is set by modifiers on the view:

ImmersiveMapView()
    .cameraPosition(.city(.paris, zoom: 15))
    .night()
    .shadows(strength: 0.6)
    .trees(isEnabled: false)

A modifier sets only the values you pass. Everything you leave out keeps its default, or the value an earlier modifier gave it, so .shadows(strength: 0.6) changes the strength and nothing else.

Settings in one place

Every modifier that configures the map also exists on ImmersiveMapSettings, the value that holds the map’s whole configuration. Only the camera position, the markers and the controllers stay on the view. Build the value once when several maps share it, or when it comes from your app’s own settings:

let settings = ImmersiveMapSettings.default
    .night()
    .shadows(strength: 0.6)

ImmersiveMapView(settings: settings)
    .cameraPosition(start)

The modifiers on the view apply over the value you pass. The same value configures a picture or a video (see Export).

Changing the settings

Pass new values whenever your state changes, and the map follows. Most changes apply on the next frame: the camera, the light and the shadows, the fog, the attribution.

A few change how the tiles are prepared, so the map is built again and reloads what it shows, from the disk cache where it can: the tile source, the style (.night() included), the labels, the caches, the pin settings, the model archive, and .msaa(). Change them when the user asks for it, not on every frame.

Next