TomTom Maps SDK for JavaScript
This is the documentation of version 1.0.0-rc.3. 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:

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…) and the user events on them. 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 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));

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