TomTom Maps SDK for JavaScript
This is the documentation of version 1.0.0-rc.0. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    Variable mapStyleLayerIDsConst

    mapStyleLayerIDs: {
        country: "Places - Country name";
        lowestBuilding: "Buildings - Underground";
        lowestLabel: "Borders - Treaty label";
        lowestPlaceLabel: "Places - Village / Hamlet";
        lowestRoadLine: "Tunnel - Railway outline";
        poi: "POI";
    } = ...

    Key layer IDs from the vector map style for positioning custom layers.

    Type Declaration

    • Readonlycountry: "Places - Country name"

      Country name label layer.

      It sits lower in the stack than most labels. Use it to position elements below country labels but above other map features.

    • ReadonlylowestBuilding: "Buildings - Underground"

      The lowest building layer in the stack.

      Use it to position content below 3D building extrusions while keeping it above flat map features like roads and terrain.

      Note: Not available in the Satellite style.

    • ReadonlylowestLabel: "Borders - Treaty label"

      The lowest labels layer in the stack.

      The most commonly used reference layer. Layers positioned before it appear below all text labels, so the map stays readable while visualizations stay prominent.

      Default for SDK modules:

      • RoutingModule route and instruction lines (its icons go on top)
      • ReachableRangesModule, PlacesModule connections and TrafficIncidentDetailsModule
      • TrafficAreaAnalyticsModule heatmap and 2D modes

      It balances visibility against obscuring map labels.

    • ReadonlylowestPlaceLabel: "Places - Village / Hamlet"

      The lowest layer for place labels.

      It sits lower in the stack than city labels. Use it to position content below all place name labels while keeping it visible above geographic features.

    • ReadonlylowestRoadLine: "Tunnel - Railway outline"

      The lowest road line layer in the stack.

      It holds the tunnel railway outlines. Use it to position content below the road network, such as base layers or features that should appear beneath transportation infrastructure.

      Note: Not available in the Satellite style.

    • Readonlypoi: "POI"

      Points of Interest layer.

      Use it to position custom content in the layer stack relative to POI icons and labels.

    These layer IDs from TomTom's vector map styles serve as anchors for positioning custom layers in the map's layer stack. SDK modules and custom implementations reference them to control where their layers appear in the rendering order (visual stacking).

    Understanding Layer Order:

    "Lowest" refers to the position in the layer stack, not to physical elevation. Layers render from bottom to top, so lower layers are drawn first and appear underneath higher ones. A layer you add "before" a reference layer goes lower in the stack and is drawn underneath it.

    How SDK Modules Use These IDs:

    RoutingModule - Positions route visualizations below labels for readability:

    // Routes appear below labels but above the base map
    const routingModule = await RoutingModule.create(map);
    // Uses mapStyleLayerIDs.lowestLabel by default; `beforeLayerConfig` moves the route lines
    const underRoads = await RoutingModule.create(map, { beforeLayerConfig: { mainLines: 'lowestRoadLine' } });

    GeometriesModule - Configurable layer positioning for polygon areas:

    // Default: on top of the map, below the geometry titles
    const geometriesModule = await GeometriesModule.create(map);

    // Custom: below buildings to show at ground level
    const geometriesModule = await GeometriesModule.create(map, {
      beforeLayerConfig: 'lowestBuilding'
    });

    // On top of everything
    const geometriesModule = await GeometriesModule.create(map, {
      beforeLayerConfig: 'top'
    });

    Custom Layer Implementation:

    // Add a highlight layer below labels
    map.addLayer({
      id: 'search-results',
      type: 'fill',
      source: 'results-source',
      paint: { 'fill-color': '#ffcc00', 'fill-opacity': 0.4 }
    }, mapStyleLayerIDs.lowestLabel);

    Style Persistence:

    These layer IDs stay the same across TomTom map style changes, such as from 'streetLight' to 'streetDark'. The SDK automatically repositions module layers against the matching reference layers in the new style, keeping the intended visual hierarchy.

    Important Notes:

    • lowestRoadLine and lowestBuilding are not available in the Satellite style
    • If a reference layer doesn't exist, a module repositioning its layers puts them on top of the style instead. A layer added with a beforeID that never appears is reported through console.error and skipped, since a missing anchor there is usually a typo.
    • By default, RoutingModule draws its lines below lowestLabel, and GeometriesModule adds its layers on top

    Settings
    Member Visibility