Base map module

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.

What this module owns: whether each base-map layer group is shown, and the user events on them. How the base map looks — label and road sizes, the ten map colours, 3D buildings, projection and sky — belongs to the Styling module. A basemap.<group> toggle knob (buildings.footprints and buildings.3d for the two building groups) writes through this module and reads the layers back, so it agrees with isVisible and the later call wins. See Who owns what, including what a style change re-applies.

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:

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

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():

const baseMap = await BaseMapModule.get(map, {
    layerGroupsVisibility: {
        mode: 'include',
        names: ['buildings2D', 'buildings3D'],
        visible: false
    }
});

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

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

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

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

Dynamic control

Changing visibility

Control base map visibility dynamically based on application state:

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

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

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

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

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

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

Applying configuration updates

Apply configuration changes at runtime without map reinitialization:

baseMap.applyConfig({
    layerGroupsVisibility: {
        visible: true,
        mode: 'include',
        names: ['land', 'water', 'cityLabels']
    }
});

Advanced layer group management

Create specialized map displays for different application contexts:

// Navigation-focused configuration
const navigationConfig = {
    layerGroups: {
        mode: 'include',
        names: ['land', 'water', 'roads', 'roadLabels', 'roadShields']
    }
};

// Urban planning configuration
const urbanConfig = {
    layerGroups: {
        mode: 'include',
        names: ['land', 'buildings2D', 'buildings3D', 'roads']
    }
};

// Geography education configuration
const geoConfig = {
    layerGroups: {
        mode: 'include',
        names: ['land', 'water', 'borders', 'countryLabels', 'capitalLabels']
    }
};

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

Event handling

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

const baseMap = await BaseMapModule.get(map);

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

    if (feature.properties.building) {
        showBuildingDetails(feature.properties);
    } else if (feature.properties.road_name) {
        showRoadInformation(feature.properties);
    }
});

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

Integration patterns

Multi-module coordination

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

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

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

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

// Coordinate visibility for focused displays
function showNavigationView() {
    baseMap.setVisible(true, {
        layerGroups: {
            mode: 'include',
            names: ['roads', 'roadLabels', 'roadShields']
        }
    });
    trafficIncidentsModule.setVisible(true);
    poisModule.setVisible(false);
}

Responsive map configuration

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

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

    if (isMobile) {
        // Simplified display for mobile
        baseMap.setVisible(true, {
            layerGroups: {
                mode: 'include',
                names: ['land', 'water', 'roads', 'cityLabels']
            }
        });
    } else if (isHighDensity) {
        // Rich detail for high-resolution displays
        baseMap.setVisible(true, {
            layerGroups: {
                mode: 'include',
                names: ['land', 'water', 'buildings3D', 'roads', 'roadLabels', 'houseNumbers']
            }
        });
    }
}

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.