Base Map Module

VERSION 0.41.1 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,
    BaseMapModule,
    POIsModule,
    StandardStyleID,
    standardStyleIDs,
    TomTomMap,
} from '@tomtom-org/maps-sdk/map';
import './style.css';
import { API_KEY } from './config';

// (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,
        },
    });

    const layerGroups: BaseMapLayerGroupName[] = [
        'water',
        'land',
        'borders',
        'buildings2D',
        'buildings3D',
        'houseNumbers',
        'roadLines',
        'roadLabels',
        'roadShields',
        'placeLabels',
        'smallerTownLabels',
        'cityLabels',
        'capitalLabels',
        'stateLabels',
        'countryLabels',
    ];

    for (const layerGroup of layerGroups) {
        const module = await BaseMapModule.get(map, { layerGroupsFilter: { mode: 'include', names: [layerGroup] } });
        document
            .querySelector(`#sdk-example-toggle-${layerGroup}`)
            ?.addEventListener('click', (ev) => module.setVisible((ev.target as HTMLInputElement).checked));
    }
    const poisModule = await POIsModule.get(map);
    document
        .querySelector('#sdk-example-togglePOIs')
        ?.addEventListener('click', (ev) => poisModule.setVisible((ev.target as HTMLInputElement).checked));

    const stylesSelector = document.querySelector('#sdk-example-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),
    );
})();

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, borders, buildings2D, buildings3D, houseNumbers, roadLines, roadLabels, roadShields, placeLabels, 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);

Base Map Initialization without Visibility Control

Set up layer group filtering without initial visibility, which can be later set using setVisible()

1
const baseMap = await BaseMapModule.get(map, {
2
    layerGroupsFilter: {
3
        mode: 'include',
4
        names: ['roadLines', 'roadLabels', 'buildings2D']
5
    }
6
});

Advanced Base Map Initialization

Configure the module to include only specific layer groups for specialized applications:

Layer Group Filter Behavior:

The layerGroupsFilter configuration controls layer visibility through two modes:

Exclude Mode:
- visible: false - Hides all layers except those specified in names
- visible: true - Adds all layers back to the map except the layers mentioned in names.
Note: This will not hide the layers mentioned in names if they are already present.
Include Mode:
- visible: false - Hides only the layers specified in names
- visible: true - Shows only the layers specified in names

1
// Include Mode Examples
2

3
// Include mode with visible: true - Shows land, water, and borders layers
4
const includeVisible = await BaseMapModule.get(map, {
5
    layerGroupsFilter: {
6
        mode: 'include',
7
        names: ['land', 'water', 'borders']
8
    },
9
    visible: true
10
});
11

12
// Include mode with visible: false - Hides buildings layers
13
const includeHidden = await BaseMapModule.get(map, {
14
    layerGroupsFilter: {
15
        mode: 'include',
16
        names: ['buildings2D', 'buildings3D']
17
    },
18
    visible: false
19
});
20

21
// Exclude Mode Examples
22

23
// Exclude mode with visible: true - Shows all layers EXCEPT the specified ones.
24
// Eg., if placeLabels is already  present, it won't be hidden. It needs to be explicitly removed first.
25
const excludeVisible = await BaseMapModule.get(map, {
26
    layerGroupsFilter: {
27
        mode: 'exclude',
28
        names: ['placeLabels', 'roadLabels', 'cityLabels']
29
    },
30
    visible: true
31
});
32

33
// Exclude mode with visible: false - Hides ALL layers EXCEPT the specified ones
34
const excludeHidden = await BaseMapModule.get(map, {
35
    layerGroupsFilter: {
36
        mode: 'exclude',
37
        names: ['land', 'water']
38
    },
39
    visible: false
40
});

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
}

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', 'roadLines', 'roadLabels', 'roadShields']
6
    }
7
};
8

9
// Urban planning configuration
10
const urbanConfig = {
11
    layerGroups: {
12
        mode: 'include',
13
        names: ['land', 'buildings2D', 'buildings3D', 'roadLines']
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
    layerGroupsFilter: {
6
        mode: 'exclude',
7
        names: ['placeLabels'] // Let POIs handle place labeling
8
    }
9
});
10

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

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

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', 'roadLines', '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', 'roadLines', '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 http://docs.tomtom.com/maps-sdk-js/examples .