TomTom Maps SDK for JavaScript
This is the documentation of version 1.0.0-rc.2. 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 above every other place label and the POIs; only the traffic incident markers are higher. Use it to position content below country labels but above every other label.

    • ReadonlylowestBuilding: "Buildings - Underground"

      The lowest building layer in the stack, and the lowest of these anchors.

      It holds the underground buildings, under the 2D building footprints and the whole road network. Use it to position content below buildings, roads and labels while keeping it above land cover and water. To stay above the roads but below the 3D buildings, use lowestLabel.

      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. The 3D buildings sit directly above it, so content positioned before it also stays under them, and above the roads.

    • 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: under the building footprints and the whole road network
    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