Skip to main content

Display overlays

Last updated: April 17, 2026 | 2 minutes read

Overlays provide enhanced, layered information on top of your base map. They offer dynamic, interactive, and customized data that adds contextual value to map elements.

Get available overlays​

Use OverlayServiceContext to retrieve the current overlay catalog.

let overlayService = OverlayServiceContext()

if let collection = overlayService.getAvailableOverlays() {
    for overlay in collection.getOverlays() {
        print("overlay id=\(overlay.getUid()) name=\(overlay.getName())")
    }
}

Disable overlays by applying a custom map style from Magic Lane Map Studio with certain overlays disabled, or by using the disableOverlay method:

Disable and enable overlays​

Disable or enable whole overlays by UID.

let overlayService = OverlayServiceContext()
let publicTransportOverlayId = Int32(CommonOverlayIdentifier.publicTransport.rawValue)

let disableResult = overlayService.disableOverlay(publicTransportOverlayId)
print("disable result: \(disableResult)")

let enableResult = overlayService.enableOverlay(publicTransportOverlayId)
print("enable result: \(enableResult)")

Disable a specific category by providing both overlay and category IDs:

if let overlays = overlayService.getAvailableOverlays(),
   let overlay = overlays.getOverlayAt(0),
   let category = overlay.getCategories().first {

    _ = overlayService.disableOverlay(overlay.getUid(), category: category.getUid())
}
danger

To disable or enable an overlay the SDK must be online. If the SDK is offline, the methods will return SDKErrorCodeNotFound. Check with isOnlineConnection() from GEMSdk before calling these methods.

Check overlay state​

let enabled = overlayService.isOverlayEnabled(publicTransportOverlayId)
print("overlay enabled: \(enabled)")

Select overlay items on map​

Use cursor-based selection from MapViewController:

let selectedOverlays = mapViewController.getCursorSelectionOverlayItems()

for item in selectedOverlays {
    print("item id=\(item.getUid()) name=\(item.getName())")
}

You can also handle overlay selection in MapViewControllerDelegate using didSelectOverlays callbacks.

Last updated on