TomTom Maps SDK for JavaScript
This is the documentation of version 0.63.0. Go to the latest version, 1.0.0-rc.5.

Base map module

The Base Map Module shows and hides the layers of the base map — land, water, buildings, roads, borders and their labels — by layer group, and reports the user events on them. The demo below toggles each group:

What this module owns: whether each base-map layer group is shown — 3D buildings and road shields included — and the road parts within them (road arrows, exit numbers…), and the user events on them. How the base map looks — label and road sizes, the ten map colours, projection and sky — belongs to the Styling Foundations module. See Who owns what.

Layer groups

The Base Map Module organizes map content into logical layer groups that can be controlled independently. It supports the following groups, exported as baseMapLayerGroupNames:

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

Every setting as data

baseMapKnobCatalogue lists every setting of the module's configuration with its kind and a description. Each id is the setting's path in the config, so a UI can build its controls from it, with no map loaded:

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

const groupToggles = baseMapKnobCatalogue.filter(({ id }) => id.startsWith('groups.'));
// [{ id: 'groups.land.visible', kind: 'toggle', description: 'The `land` layer group: …' }, …]

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.

Road parts

roads shows or hides four parts of the roads on their own, finer than the layer groups: the motorway exit number badges, the one-way arrows, the dashed marking of restricted roads, and the roads under construction.

const baseMap = await BaseMapModule.get(map, {
    roads: { exitNumbers: { visible: false }, arrows: { visible: false } },
});
setKnob(baseMap, baseMapKnobCatalogue, 'roads.underConstruction.visible', false);

A part never shows while its layer group is hidden, and showing the group again keeps a part's false. Unset, a part is drawn as the style ships it.

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 the { show, values } filter that POIs and traffic filter by:

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

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

// Show everything except the labels
baseMap.setVisible(true, {
    layerGroups: { show: 'all-except', values: ['allPlaceLabels', 'roadLabels', 'cityLabels'] }
});

Dynamic control

Changing visibility

Control base map visibility dynamically based on application state:

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

// Read the setting back
if (!baseMap.isVisible()) {
    console.log('Base map is hidden');
}

isVisible() reads the settings rather than the layers: visible, then the groups over it, the later winning. A layer none of them reaches reports what the style draws.

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 = { show: 'only', values: ['buildings3D'] };

// Until a call sets the group, this is what the style 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. The road parts stay set.

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

Building a map up group by group

Showing groups one after another turns the base map into an animation: the demo below hides everything, then shows one layer group per second — borders, buildings, land, roads, labels — and the traffic and POI layers after them.

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

Combining with other modules

The base map, the POIs and the traffic layers are separate modules over one style, so a focused view sets each of them:

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

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

// A navigation view: roads and their labels, live incidents, no POIs
const showNavigationView = () => {
    baseMap.setVisible(false);
    baseMap.setVisible(true, {
        layerGroups: { show: 'only', values: ['land', 'water', 'roads', 'roadLabels', 'roadShields'] }
    });
    trafficIncidentsModule.setVisible(true);
    poisModule.setVisible(false);
};

API reference

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

Related guides and examples

Related guides

Related examples