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, roads.shields for roadShields) writes through this module and reads the layers back, so it agrees with isVisible and the later call wins, across a style change too. The knobs inside a group — roads.arrows, roads.restricted, roads.underConstruction, roads.exitNumbers — only hide their layers within what this module shows. See Who owns what.

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

groups sets the initial state of each layer group, and can be changed later with setVisible():

const baseMap = await BaseMapModule.get(map, {
    groups: { buildings2D: { visible: false }, buildings3D: { visible: false } }
});

visible applies to every layer first, then each entry of groups in the order given, so a later entry wins where two groups share layers (allPlaceLabels and cityLabels). Whatever neither sets is drawn as the style ships it — and so is a group whose entry leaves visible out, which is how to keep a few groups exactly as the style draws them:

// Only land, water and roads, each as the style ships it
await BaseMapModule.get(map, { visible: false, groups: { land: {}, water: {}, roads: {} } });

Showing a group shows every layer in it, including the ones the style ships hidden, such as detailed road markings.

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, which setVisible leaves as they were

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

Every setVisible call is kept in getConfig().groups (a call without groups replaces the record with visible), so a setStyle restores all of them, in order. A call over a group also takes it over from its styling toggle knob, which it removes from styling.getConfig().

Applying configuration updates

applyConfig replaces the whole configuration: what the new one leaves out goes back to how the style ships it. updateConfig merges into the current configuration, key by key.

// Hides the house numbers; every other group goes back to the style
baseMap.applyConfig({ groups: { houseNumbers: { visible: false } } });

// Also hides the ferries, keeping the house numbers hidden
baseMap.updateConfig({ groups: { ...baseMap.getConfig()?.groups, ferries: { visible: false } } });

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);

To restyle groups of layers in a style of your own rather than hide them, use Map Maker's modules and load the result as a custom style.

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, {
    groups: { allPlaceLabels: { visible: false } } // Let POIs handle place labeling
});

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.