Base map module

VERSION 0.53.0 PUBLIC PREVIEW

The Base Map Module in the TomTom Maps SDK provides comprehensive control over the fundamental map layers that form the visual foundation of your maps. This module encompasses essential cartographic elements including land, water, buildings, roads, borders, and various label types, enabling precise customization of map appearance and functionality.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import {
    BaseMapLayerGroupName,
    BaseMapLayerGroups,
    BaseMapModule,
    baseMapLayerGroupNames,
    POIsModule,
    StandardStyleID,
    standardStyleIDs,
    TomTomMap,
} from '@tomtom-org/maps-sdk/map';
import './style.css';
import { API_KEY } from './config';
import { initTogglePanel } from './togglePanel';

// Turn a camelCase group name into a readable label, e.g. 'roadLabels' -> 'Road labels'.
const humanizeGroupName = (name: string): string => {
    const spaced = name.replace(/([A-Z])/g, ' $1').toLowerCase();
    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
};

// Build one toggle row per base-map layer group and return its checkbox.
const addToggleRow = (container: HTMLElement, group: BaseMapLayerGroupName): HTMLInputElement => {
    const label = document.createElement('label');
    label.className = 'ui-toggle-label';
    label.innerHTML = `
        <input type="checkbox" class="ui-toggle-input" id="ui-toggle-${group}">
        <span class="ui-toggle-switch"></span>
        ${humanizeGroupName(group)}`;
    container.appendChild(label);
    return label.querySelector('input') as HTMLInputElement;
};

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-GB' });

(async () => {
    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            center: [-74.06332, 40.72732],
            zoom: 12,
        },
    });

    // One base map module controls every group: `setVisible` and `isVisible` both take the group
    // to act on, so a toggle per group needs no module per group.
    const baseMap = await BaseMapModule.get(map);

    const togglesContainer = document.querySelector('#ui-baseMapToggles') as HTMLElement;
    for (const layerGroup of baseMapLayerGroupNames) {
        const layerGroups: BaseMapLayerGroups = { mode: 'include', names: [layerGroup] };
        const checkbox = addToggleRow(togglesContainer, layerGroup);
        // Reflect the group's real starting visibility (e.g. buildings3D ships hidden) rather than assuming.
        checkbox.checked = baseMap.isVisible({ layerGroups });
        checkbox.addEventListener('change', () => baseMap.setVisible(checkbox.checked, { layerGroups }));
    }

    const poisModule = await POIsModule.get(map);
    document.querySelector('#ui-togglePOIs')?.addEventListener('change', (event) => {
        poisModule.setVisible((event.target as HTMLInputElement).checked);
    });

    const stylesSelector = document.querySelector('#ui-mapStyles') as HTMLSelectElement;
    for (const id of standardStyleIDs) {
        stylesSelector.add(new Option(id));
    }
    stylesSelector.addEventListener('change', (event) =>
        map.setStyle((event.target as HTMLOptionElement).value as StandardStyleID),
    );

    initTogglePanel();
})();

Open Sandbox

Overview

The Base Map Module manages vector tile layers that represent the core geographic and cartographic features of TomTom maps. Unlike specialized modules that handle specific data types like traffic or POIs, the Base Map Module controls the fundamental visual elements that provide geographic context and navigation reference.

Core Layer Categories:

Geographic features including land cover, water bodies, and political borders
Built environment with 2D and 3D building representations
Transportation infrastructure featuring road networks and navigation aids
Labeling system providing hierarchical place names and identifiers
Address information including house numbers and location markers

Key Capabilities:

Layer group management for controlling specific map feature categories
Selective visibility enabling focused map displays for specialized applications
Dynamic configuration supporting runtime changes without map reloads
Event handling for interactive map experiences with base map elements

Layer groups

The Base Map Module organizes map content into logical layer groups that can be controlled independently and supports the following layers,

land, water, natureLabels, roads, railways, ferries, buildings2D, buildings3D, borders, roadLabels, roadShields, houseNumbers, allPlaceLabels, smallerTownLabels, cityLabels, capitalLabels, stateLabels, countryLabels

Basic setup

First set up your project and map following the Map quickstart guide and ensure you have a running TomTomMap instance.

Standard base map initialization

For comprehensive base map functionality, initialize the module with default settings:

1
import { BaseMapModule } from '@tomtom-org/maps-sdk/map';
2

3
const baseMap = await BaseMapModule.get(map);

Initializing with a layer group hidden

layerGroupsVisibility sets the initial state of part of the map, and can be changed later with setVisible():

1
const baseMap = await BaseMapModule.get(map, {
2
    layerGroupsVisibility: {
3
        mode: 'include',
4
        names: ['buildings2D', 'buildings3D'],
5
        visible: false
6
    }
7
});

Layer group modes

Every map has one base map module — a second BaseMapModule.get(map) returns the same instance. You name the layer groups you care about per call instead: setVisible / isVisible for visibility, and events.where({ layerGroups }) for events, which takes its own cursor configuration.

Both take a mode:

Include Mode: acts only on the layers in names
Exclude Mode: acts on every layer except those in names

1
// Show only land, water and borders
2
baseMap.setVisible(false);
3
baseMap.setVisible(true, { layerGroups: { mode: 'include', names: ['land', 'water', 'borders'] } });
4

5
// Hide the buildings layers, leaving the rest as it is
6
baseMap.setVisible(false, { layerGroups: { mode: 'include', names: ['buildings2D', 'buildings3D'] } });
7

8
// Show everything except the labels
9
baseMap.setVisible(true, {
10
    layerGroups: { mode: 'exclude', names: ['allPlaceLabels', 'roadLabels', 'cityLabels'] }
11
});

Dynamic control

Changing visibility

Control base map visibility dynamically based on application state:

1
// Toggle overall base map visibility
2
baseMap.setVisible(false);
3

4
// Check current visibility state
5
if (baseMap.isVisible()) {
6
    console.log('Base map is currently visible');
7
}

setVisible and isVisible both accept the layer groups to act on, so one module backs a control per group — no second module needed:

1
const layerGroups = { mode: 'include', names: ['buildings3D'] };
2

3
// Reflect what the style actually ships (buildings3D usually starts hidden)
4
checkbox.checked = baseMap.isVisible({ layerGroups });
5

6
checkbox.addEventListener('change', () => baseMap.setVisible(checkbox.checked, { layerGroups }));

Applying configuration updates

Apply configuration changes at runtime without map reinitialization:

1
baseMap.applyConfig({
2
    layerGroupsVisibility: {
3
        visible: true,
4
        mode: 'include',
5
        names: ['land', 'water', 'cityLabels']
6
    }
7
});

Advanced layer group management

Create specialized map displays for different application contexts:

1
// Navigation-focused configuration
2
const navigationConfig = {
3
    layerGroups: {
4
        mode: 'include',
5
        names: ['land', 'water', 'roads', 'roadLabels', 'roadShields']
6
    }
7
};
8

9
// Urban planning configuration
10
const urbanConfig = {
11
    layerGroups: {
12
        mode: 'include',
13
        names: ['land', 'buildings2D', 'buildings3D', 'roads']
14
    }
15
};
16

17
// Geography education configuration
18
const geoConfig = {
19
    layerGroups: {
20
        mode: 'include',
21
        names: ['land', 'water', 'borders', 'countryLabels', 'capitalLabels']
22
    }
23
};
24

25
// Apply based on application mode
26
baseMap.setVisible(true, navigationConfig);

Event handling

The Base Map Module provides event handling capabilities for interactive applications:

1
const baseMap = await BaseMapModule.get(map);
2

3
// Handle clicks on base map features
4
baseMap.events.on('click', (feature, lngLat) => {
5
    console.log('Base map feature clicked:', feature.properties);
6

7
    if (feature.properties.building) {
8
        showBuildingDetails(feature.properties);
9
    } else if (feature.properties.road_name) {
10
        showRoadInformation(feature.properties);
11
    }
12
});
13

14
// Handle hover for feature identification
15
baseMap.events.on('hover', (feature, lngLat) => {
16
    showFeaturePreview(feature.properties, lngLat);
17
});

Integration patterns

Multi-module coordination

Coordinate the Base Map Module with other specialized modules for comprehensive applications:

1
import { BaseMapModule, POIsModule, TrafficIncidentsModule } from '@tomtom-org/maps-sdk/map';
2

3
// Initialize modules with complementary configurations
4
const baseMap = await BaseMapModule.get(map, {
5
    layerGroupsVisibility: {
6
        mode: 'include',
7
        names: ['allPlaceLabels'], // Let POIs handle place labeling
8
        visible: false
9
    }
10
});
11

12
const poisModule = await POIsModule.get(map);
13
const trafficIncidentsModule = await TrafficIncidentsModule.get(map);
14

15
// Coordinate visibility for focused displays
16
function showNavigationView() {
17
    baseMap.setVisible(true, {
18
        layerGroups: {
19
            mode: 'include',
20
            names: ['roads', 'roadLabels', 'roadShields']
21
        }
22
    });
23
    trafficIncidentsModule.setVisible(true);
24
    poisModule.setVisible(false);
25
}

Responsive map configuration

Adapt base map display based on viewport size and device capabilities:

1
function updateMapConfiguration() {
2
    const isMobile = window.innerWidth < 768;
3
    const isHighDensity = window.devicePixelRatio > 1.5;
4

5
    if (isMobile) {
6
        // Simplified display for mobile
7
        baseMap.setVisible(true, {
8
            layerGroups: {
9
                mode: 'include',
10
                names: ['land', 'water', 'roads', 'cityLabels']
11
            }
12
        });
13
    } else if (isHighDensity) {
14
        // Rich detail for high-resolution displays
15
        baseMap.setVisible(true, {
16
            layerGroups: {
17
                mode: 'include',
18
                names: ['land', 'water', 'buildings3D', 'roads', 'roadLabels', 'houseNumbers']
19
            }
20
        });
21
    }
22
}

API reference

For complete documentation of all BaseMapModule properties, methods, and types, see the BaseMapModule API Reference.

Examples

For complete base map implementation examples and advanced layer group management patterns, go to the examples gallery.