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

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:

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 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, readable 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).

Initializing with a layer group hidden

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

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

Road parts

roads shows or hides four parts of the roads on their own, 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 showing the group again keeps a part's false. Unset, a part 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: what 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 — 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 module's events fire on the base map wherever no other module's feature is on top, which makes them the place 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));

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