The unified events interface of this module, for both user interactions and module lifecycle events.
User interaction events are click, contextmenu, hover and long-hover:
const unsub = baseMap.events.on('click', (feature, lngLat) => {
console.log('Clicked on:', feature.properties);
});
baseMap.events.off('hover'); // remove by type
The lifecycle event is config-change:
const unsub = baseMap.events.on('config-change', (config) => {
console.log('Config changed:', config);
});
unsub(); // remove by returned function
The MapLibre source and layer IDs of all sources this module creates and manages.
A record mapping each source name to its MapLibre source ID and an array of the IDs of that source's layers.
Use these IDs to:
const ids = myModule.sourceAndLayerIDs;
console.log(ids);
// {
// mySource: {
// sourceID: 'my-source-id',
// layerIDs: ['layer-1', 'layer-2']
// }
// }
// Use with MapLibre API
const map = myModule.mapLibreMap;
ids.mySource.layerIDs.forEach(layerId => {
map.setLayoutProperty(layerId, 'visibility', 'visible');
});
Applies a configuration to this module.
The module updates its behaviour and appearance to match. It stores the configuration and reapplies it automatically when the map style changes.
The configuration to apply. Pass undefined to reset it to the default values.
The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.
Use it for settings your code writes. It takes every setting, typed, including the ones no knob covers (layer specs, callbacks, MapLibre expressions), and checks no value at run time. For settings held as data, from a control, storage or a language model, use setKnobs.
// Apply a new configuration
myModule.applyConfig({ visible: true, color: '#E63312' });
// Reset to default configuration
myModule.applyConfig(undefined);
Returns a shallow copy of the current module configuration, or undefined if none is applied.
A shallow copy of the current configuration, or undefined. It is a copy so that you
can't modify the internal state by accident.
Only the top-level properties are copied. Nested objects and arrays still reference the original configuration. This is enough for most use cases, but keep it in mind with complex configurations.
// Apply a configuration
myModule.applyConfig({ visible: true, color: '#E63312' });
// Later, retrieve the current configuration
const currentConfig = myModule.getConfig();
console.log(currentConfig); // { visible: true, color: '#E63312' }
// When no config is applied
myModule.resetConfig();
console.log(myModule.getConfig()); // undefined
Returns the managed layer ids of a single base-map layer group.
The layer group to look up.
The group's layer ids in style draw order, or an empty array if there are none. Each call returns a fresh array that is safe to mutate.
Returns the base-map layer ids this module manages in the current style, grouped by BaseMapLayerGroupName.
A record with an entry for every layer group, an empty array when the style
has no layers for it. Layer ids keep their style draw order within each group. Groups
overlap by design, so a layer id can appear under several, like a city label in both
cityLabels and allPlaceLabels.
Whether the base map, or the layer groups asked about, is set to be shown.
Optionaloptions: { layerGroups?: BaseMapLayerGroups }
Optional settings for fine-grained control.
OptionallayerGroups?: BaseMapLayerGroupsLayer groups to ask about instead of all layers.
true if at least one of the layers asked about is set to show, false if all are
set to hide.
It reads the settings, not the map: visible, then the groups over it, in the order
setVisible writes them. The last that reaches a layer wins.
A layer none of them reaches answers with what the style draws, which is how a per-group control reflects the state the style starts in.
Resets this module's configuration to its default values.
It clears any applied configuration and restores the module to its initial state, the same
as calling applyConfig(undefined).
The module then behaves as if no configuration was ever applied. Any custom settings, styling or behaviour changes are replaced with default values.
// Apply some configuration
myModule.applyConfig({ visible: true, color: '#E63312' });
// Later, reset to defaults
myModule.resetConfig();
Sets the visibility of base map layers.
true to show layers, false to hide them.
Optionaloptions: { layerGroups?: BaseMapLayerGroups }
Optional settings for fine-grained control.
OptionallayerGroups?: BaseMapLayerGroupsLayer groups to target instead of all layers.
options.layerGroups: Affects all base map layersoptions.layerGroups showing only its values: Affects only those layer groupsall-except them: Affects every layer outside those groups, which stay as they wereEvery call is kept in the configuration's groups or visible, so a style change restores
all of them. The road parts, such as roads.arrows.visible, stay set.
The available groups are land, water, buildings2D, roads, railways,
ferries, borders, buildings3D, natureLabels, roadLabels,
roadShields, houseNumbers, smallerTownLabels, stateLabels,
cityLabels, allPlaceLabels, capitalLabels, countryLabels.
See BaseMapLayerGroupName.
Show/hide all layers:
baseMap.setVisible(false); // Hide everything
baseMap.setVisible(true); // Show everything
Control specific groups:
// Hide only buildings
baseMap.setVisible(false, {
layerGroups: {
show: 'only',
values: ['buildings2D', 'buildings3D']
}
});
// Show everything except labels
baseMap.setVisible(true, {
layerGroups: {
show: 'all-except',
values: ['allPlaceLabels', 'cityLabels', 'countryLabels']
}
});
Changes part of the configuration and keeps the rest.
The given properties are laid over the current configuration one level deep, so a nested
object you pass replaces the one that was there. The result is applied with
applyConfig. This works the same on every module, whatever its applyConfig does with
a whole configuration.
The properties to change.
Use it for settings your code writes, as applyConfig: typed, and not checked at run time. To change nested values and keep the ones beside them, or to set values held as data, use setKnobs, which reaches each by its path and checks it.
routing.applyConfig({ displayUnits: { distance: { type: 'imperial_us' } }, color: '#0a3653' });
routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial
applyConfig to apply a whole configuration
ProtectedwaitStaticgetAsynchronously retrieves a BaseMapModule instance for the given map.
This is the recommended way to create a BaseMapModule. It ensures the map is fully loaded before initializing the module.
The TomTomMap instance to attach this module to.
Optionalconfig: BaseMapModuleConfig
Optional configuration for module initialization.
A promise that resolves to the initialized BaseMapModule.
BaseMapModule controls the base-map source and layers the map style already provides, under
fixed global IDs, so every map has exactly one. A second get() returns the same instance, and a
config you pass to it replaces the one it holds, as applyConfig does. To work with part of the
map, name the layer groups per call, with setVisible(false, { layerGroups }) for visibility and
events.where({ layerGroups }) for events.
On initialization, it validates that the required sources exist in the map style and applies the initial configuration, if provided.
Configuration options:
visible: Initial visibility stategroups: Visibility per layer group
The module that controls the standard map layers and their visibility.
It manages the base map style's fundamental layers, including background, water, land, roads, buildings, labels, and other vector tile layers.
Remarks
This module owns whether each base-map layer group is shown, and the road parts within them (
roads.arrows.visible,roads.exitNumbers.visible, …), which never show in a group it hides. StylingFoundationsModule knobs set how the base map looks. See Who owns what. baseMapKnobCatalogue lists every setting of its configuration.It manages these layers:
It doesn't include:
Use it to:
Example
Basic usage:
Example
Working with layer groups:
Example
Event handling:
See