Learning › Frontend › MapLayersAndBasemaps
Edit this page

Map layers, basemaps, and Azure Maps

Azure Maps setup uses the generic map-layer APIs from @itwin/core-frontend and the Azure Maps format support from @itwin/map-layers-formats.

Use @itwin/core-frontend to start the app and attach ordinary background or overlay layers. Use @itwin/map-layers-formats to register Azure Maps support, provide the Azure Maps subscription key, and apply Azure basemaps like Street, Aerial, and Hybrid.

When to use each package

Use @itwin/core-frontend for the generic map imagery workflow:

  • start IModelApp
  • provide generic map-layer credentials at startup
  • work with a Viewport, DisplayStyleState, and the standard map-layer APIs
  • attach additional background or overlay imagery layers

Use @itwin/map-layers-formats for Azure Maps-specific behavior:

  • MapLayersFormats.initialize() to register optional formats and configure the Azure Maps subscription key
  • AzureMaps.applyBackgroundMap(...) to apply Azure Maps Street, Aerial, or Hybrid basemaps
  • AzureMaps.getBackgroundMapType(...) to inspect the active Azure Maps basemap type

Typical setup order

A typical Azure Maps app does three things in order:

  1. Start IModelApp.
  2. Initialize @itwin/map-layers-formats with the Azure Maps subscription key so Azure Maps support is registered.
  3. Apply an Azure basemap through the AzureMaps helper, and then keep using the normal map-layer APIs for any additional layers.

1. Start IModelApp

export async function startIModelApp() { await IModelApp.startup({ applicationId: "myAppId" }); }

2. Register the optional map-layers-formats package and provide the Azure Maps key

export async function initializeMapLayersFormats() { await MapLayersFormats.initialize({ azureMapsOpts: { subscriptionKey: "abc123", }, }); }

This step registers the optional Azure Maps format supplied by @itwin/map-layers-formats and supplies the subscription key through azureMapsOpts.subscriptionKey. Provide the key this way so Azure-specific setup stays with the package that handles Azure Maps.

Applying Azure Maps basemaps

After startup and registration, apply Azure basemaps through the extension helper:

Azure Maps Street

export function applyAzureStreetBaseMap() { const vp = IModelApp.viewManager.selectedView; if (!vp) return; AzureMaps.applyBackgroundMap(vp.displayStyle, BackgroundMapType.Street); }

Azure Maps Aerial

export function applyAzureAerialBaseMap() { const vp = IModelApp.viewManager.selectedView; if (!vp) return; AzureMaps.applyBackgroundMap(vp.displayStyle, BackgroundMapType.Aerial); }

Azure Maps Hybrid

export function applyAzureHybridBaseMap() { const vp = IModelApp.viewManager.selectedView; if (!vp) return; AzureMaps.applyBackgroundMap(vp.displayStyle, BackgroundMapType.Hybrid); }

Hybrid is exposed as one Azure basemap choice even though its internal composition is provider-specific. Applications should request Hybrid through AzureMaps.applyBackgroundMap(...) instead of trying to assemble it manually from catalog rows or raw tile URLs.

Mixing Azure basemaps with normal map layers

Using Azure Maps for the basemap does not replace the normal map-layer APIs. After applying an Azure basemap, continue using the regular DisplayStyleState.attachMapLayer(...) workflow for additional layers.

For example, an app can apply an Azure aerial basemap and then attach an ordinary overlay layer on top:

export function applyAzureBaseMapAndOverlay() { const vp = IModelApp.viewManager.selectedView; if (!vp) return; AzureMaps.applyBackgroundMap(vp.displayStyle, BackgroundMapType.Aerial); vp.displayStyle.attachMapLayer({ mapLayerIndex: { index: 0, isOverlay: true }, settings: ImageMapLayerSettings.fromJSON({ formatId: "ArcGIS", url: "https://services.arcgisonline.com/arcgis/rest/services/Reference/World_Boundaries_and_Places/MapServer", name: "World boundaries", transparentBackground: true, }), }); }

This is the key interleaving model:

  • AzureMaps.applyBackgroundMap(...) chooses the basemap.
  • Standard map-layer APIs add any extra background or overlay content.

Inspecting the current Azure basemap type

If your UI needs to stay in sync with the active Azure basemap, use the Azure-specific inspection helper:

export function getAzureBaseMapType() { const vp = IModelApp.viewManager.selectedView; if (!vp) return undefined; return AzureMaps.getBackgroundMapType(vp.displayStyle); }

Choosing between generic and Azure-specific APIs

As a rule of thumb:

  • Use generic core APIs when you are managing views, display styles, and ordinary map layers.
  • Use AzureMaps from @itwin/map-layers-formats when you specifically want Azure Maps basemap behavior.

If your app never uses Azure Maps, it does not need to import Azure-specific helpers at all.

Before expecting imagery to appear

Even correctly configured map imagery may still not be visible unless:

  • the iModel is geolocated; and
  • the view or viewport has background maps enabled.

For more on those prerequisites, see GeoLocation of iModels and Using Views in iTwin.js.

Related topics

Last Updated: 01 June, 2026