Display overlays

_{Last updated: April 7, 2026 | 2 minutes read}

Overlays are used to provide enhanced, layered information that adds contextual value to a base map, offering users dynamic, interactive, and customized data that can be visualized on top of other map elements.

Disabling overlays

Overlays can be disabled either by applying a predefined, custom map style created in Magic Lane Map Studio, where certain overlays are already disabled, or by removing them from the visible map overlay collection, as shown below:

import { CommonOverlayId, GemError, GemMap } from '@magiclane/maps-sdk';

function disablePublicTransportOverlay(map: GemMap): void {
  const error = map.preferences.overlays.remove(CommonOverlayId.PublicTransport);

  if (error === GemError.success) {
    console.log('Public transport overlay disabled');
  } else if (error === GemError.notFound) {
    console.log('Overlay not found in the current style');
  }
}

The returned GemError is GemError.success if the overlay was removed from the visible collection, or GemError.notFound if that overlay is not currently present in the applied style.

To disable a specific category inside an overlay, use removeCategory with the overlay ID and the category ID:

import { CommonOverlayId, GemError, GemMap } from '@magiclane/maps-sdk';

function disablePublicTransportCategory(map: GemMap, categoryId: number): void {
  const error = map.preferences.overlays.removeCategory(
    CommonOverlayId.PublicTransport,
    categoryId
  );

  if (error !== GemError.success) {
    console.log(`Failed to disable category: ${GemError[error] ?? error}`);
  }
}

Enabling overlays

In a similar way, an overlay can be enabled by adding it back to the map's visible overlay collection:

import { CommonOverlayId, GemMap } from '@magiclane/maps-sdk';

function enablePublicTransportOverlay(map: GemMap): void {
  map.preferences.overlays.add(CommonOverlayId.PublicTransport);
}

To enable only a specific category of an overlay, use addCategory:

import { CommonOverlayId, GemMap } from '@magiclane/maps-sdk';

function enablePublicTransportCategory(map: GemMap, categoryId: number): void {
  map.preferences.overlays.addCategory(CommonOverlayId.PublicTransport, categoryId);
}