This is the documentation of version 1.0.0-rc.7. Go to the latest version, 1.0.0.

Base map module

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

The module decides whether each base-map layer group shows, 3D buildings and road shields included. It also owns the road parts within them (road arrows, exit numbers…), the user events on them, and how a hovered, clicked or coloured 3D building looks. How the base map looks (label and road sizes, the 10 map colours, projection and sky) belongs to the Styling Foundations module. See Who owns what.

Layer groups

The module sorts the base-map layers into the groups listed in baseMapLayerGroupNames, from the lowest drawn to the highest:

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

Every setting as data

baseMapKnobCatalogue lists every setting of the module's configuration as a knob. You can read it with no map loaded, so a UI can build its controls from it:

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

Set up a map first with the Map quickstart.

Standard base map initialization

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

const baseMap = await BaseMapModule.get(map);

Every map has one base map module. A second get() returns the same instance (style-owned modules). A configuration you pass to it replaces the current one, as applyConfig does.

Initializing with a layer group hidden

groups sets the initial state of each layer group, and setVisible changes it later:

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

Road parts

roads shows or hides four road parts separately, finer than the layer groups: exitNumbers (motorway exit number badges), arrows (one-way arrows), restricted (the dashed marking of restricted roads) and underConstruction.

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

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 a false part stays hidden when the group shows again. A part you don't set follows its group. While nothing sets the group or visible, it is drawn as the style ships it.

Layer group modes

setVisible, isVisible and events.where take the layer groups to act on as a { show, values } value filter:

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

// Hide the buildings, 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

baseMap.setVisible(false); // the whole base map

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

Applying configuration updates

applyConfig replaces the whole configuration, so anything the new one leaves out goes back to how the style ships it. updateConfig merges one level deep, so spread groups to add to it:

// 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

The demo below hides everything, then shows one layer group per second (borders, buildings, land, roads, labels), then the traffic and POI layers.

To restyle groups of layers rather than hide them, use the map colours and the styling knobs.

Event handling

The module's events fire on the base map wherever no other module's feature is on top. Use them to handle clicks on the rest of the map, such as clearing a selection:

const baseMap = await BaseMapModule.get(map);

baseMap.events.on('click', (feature, lngLat) => {
    console.log('Base map clicked at', lngLat, 'on layer', feature.layer.id);
});

// Only the road labels and shields, with a pointer cursor
baseMap.events
    .where({ layerGroups: { show: 'only', values: ['roadLabels', 'roadShields'] } }, { cursorOnHover: 'pointer' })
    .on('click', (feature) => console.log(feature.properties.name));

A base-map feature a handler reaches takes the event as the feature state eventState (hover, long-hover, click or contextmenu), and loses the hover the moment the pointer leaves it. The 3D buildings react to it once you give them a colour, as the next section shows.

Hovered, clicked and coloured 3D buildings

To highlight the 3D building under the pointer or the one clicked, set the colour it turns towards in buildings3D, then listen to the buildings3D layer group:

const baseMap = await BaseMapModule.get(map, {
    groups: { buildings3D: { visible: true } },
    buildings3D: { hover: { color: '#f3a712' }, click: { color: '#e4572e', intensity: 0.8 } }
});

baseMap.events
    .where({ layerGroups: { show: 'only', values: ['buildings3D'] } }, { cursorOnHover: 'pointer' })
    .on('click', (building) => console.log(building.id, building.properties));

The example below lights up the buildings of Midtown Manhattan and paints the selected one:

To give single buildings a colour of their own, call setBuildingColors with CSS colours by feature id:

baseMap.events
    .where({ layerGroups: { show: 'only', values: ['buildings3D'] } })
    .on('click', (building) => {
        baseMap.setBuildingColors({ ...baseMap.getBuildingColors(), [building.id]: '#29335c' });
    });

Highlight buildings you know by place

To highlight buildings on a map of your own, such as the offices of a campus or the venues of an event, name each one by a position inside it. getBuildingIdAt returns the id of the building standing there:

const venues = [[-73.98444, 40.75566], [-73.98685, 40.75552]];

// `once('idle')` waits for the next idle, which a settled map never fires.
if (!map.mapLibreMap.loaded()) await map.mapLibreMap.once('idle');
const colors = {};
for (const position of venues) {
    const id = baseMap.getBuildingIdAt(position);
    if (id !== undefined) colors[id] = '#e4572e';
}
baseMap.setBuildingColors(colors);

For buildings with façades, roofs and glass, use the Landmarks 3D plugin, which takes the same hover and click settings. Unlike these buildings, its own turn towards the map's accent while you leave the colours unset.

Combining with other modules

The base map, the POIs and the traffic layers are separate modules over one style, so for a focused view, set 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
baseMap.setVisible(false);
baseMap.setVisible(true, {
    layerGroups: { show: 'only', values: ['land', 'water', 'roads', 'roadLabels', 'roadShields'] }
});
trafficIncidentsModule.setVisible(true);
poisModule.setVisible(false);

API reference

BaseMapModule API reference

Related guides and examples

Related guides

Related examples