Map modules

A map module adds one capability to a TomTomMap, such as showing places or routes, filtering traffic, shading terrain or restyling the whole map. Every module follows the contract this page describes:

• A module is style-owned or data-owned, which decides its factory and how many instances a map takes.
• You configure a module at creation, then change it with applyConfig(config), updateConfig(partial) and resetConfig(). getConfig() reads it back and events.on('config-change', …) reports changes.
• Each module publishes its settings as a knob catalogue, and setKnob and setKnobs set them by id, checking each value. Changing a setting says when to use them and when to use the configuration methods.
• The SDK restores data, configuration and layer placement after every setStyle.
• Each module has typed user events that hand you your original data.
• Modules are tree-shaken, so a module you don't import isn't in your bundle.

Types of modules

Who owns the sources and layers a module controls decides the factory you call and how many instances make sense on one map.

Style-owned modules: get(map, config?)

• They control sources and layers the map style already provides under fixed, global ids, such as the base map, POIs, the traffic tiles and the terrain elevation. They display no data of their own.
• There is one per map. get() is a lookup, so a second call returns the same instance. Two components can each ask for the terrain without sharing a reference.
• get(map) without a configuration leaves its configuration as it is. With one, it applies it to the existing instance, as applyConfig does. StylingFoundationsModule merges it instead, as updateConfig does.
• If the style lacks their style part, the traffic and terrain modules' get() adds it.
• To handle events on part of what a module covers, scope its events instead of looking for a second module.

Data-owned modules: create(map, config?)

• They add the GeoJSON sources, layers and sprite images they need, and own them for their whole lifetime. Every id has a per-instance suffix.
• A map can have many of them. create() builds a new, independent module every time, for example one set of places per search or one route per plan.

Per-module reference

Who owns what

Everything visible on the map has exactly one owner, whoever owns its layers. Every module has knobs of its own. Each style-owned module decides whether and how its part of the loaded style shows. The Styling Foundations module sets the foundations that reach across every part: sizes, the map colours, projection and sky. Each data-owned instance decides everything about the layers it adds itself. In the diagram, the dashed line marks the only place a knob reaches past its module. There, the data-owned modules read the accent as their default colour.

In detail:

Two consequences:

• The rows don't cross. Knobs on the loaded style never write a data-owned module's layers, and a data-owned module never restyles the base map under it. You recolour a route in the RoutingModule configuration, and the roads it runs on with colors.roadMajor. The accent and the borrowed looks are read, not written.
• The foundations and a part's own look meet on the same layers, and compose. One engine per map applies every style knob, whichever module holds it. So labels.sizeFactor and the POIs' sizeFactor multiply on the POI labels, and all of them land on top after a style switch.

Within a style-owned module, the finer settings only narrow what its coarser ones show. A road part or the POI micro markers never show while their layer group or the POIs are hidden. Showing those again keeps a part's false. The POIs' zoomShift rewrites the same layer filters that filters.categories narrows, in either order.

To find the layers a module owns, read its sourceAndLayerIDs: the MapLibre source id and layer ids of each of its sources. Every module has it, style-owned or data-owned. Use it when your own code writes MapLibre layer properties and should leave a module's layers alone. On the base map, getLayerIds(group) narrows the list to one layer group. A road part, such as the arrows, has no layer list of its own. The Styling Foundations module owns no layers, so its list is empty.

const pois = await POIsModule.get(map);
pois.sourceAndLayerIDs.pois.layerIDs; // the POI layers, micro markers included

Read it again after a style switch or a configuration change, since a data-owned module can add or remove layers, such as a route's section layers.

Each module guide opens with a What this module owns line that applies this rule.

Writing to a module's layers yourself

Changing a module's layers with map.mapLibreMap is a fallback for visual tweaks no knob offers. It doesn't combine cleanly with the modules, so expect to set your values again:

• A style switch drops everything you wrote. The knobs land again on the new style, and your writes don't.
• A knob never builds on your value. It works its value out from the style's or the module's own, as How knobs work explains.
• A knob, or any other change to a module's configuration, replaces your value only on the layers and properties it changes, and leaves the rest. Changing a geometries module's line.color keeps the fill opacity and label size you set. The Styling Foundations knobs do the same on the base-map and POI layers they reach. For a custom GeoJSON module, a change replaces the properties your new layer specs set differently.
• A layer a data-owned module removes and adds back loses what you wrote on it. For example, the traffic incident details outline is removed by highlight: false.
• Visibility belongs to the module:
  • The traffic, terrain and data-owned modules set it on all their layers at every configuration change, so a layer you hid shows again.
  • The base map sets it only on the layer groups and road parts a change toggles.
  • The POIs module reads it back from its layers. If you hide all of them yourself, the module counts as hidden, and its next change shows them again.
  • The Styling Foundations module never sets visibility.

Changing a setting

A module takes its settings in two ways, and which one you use depends on where the values come from:

• The configuration methods are for settings your code writes. applyConfig(config) replaces the whole configuration, and updateConfig(partial) changes the top-level properties you give it. They take every setting, typed, including the ones no knob covers, such as layer specs, callbacks and MapLibre expressions.
• The knob functions are for settings held as data, an id and a value from a control, storage, a URL or a language model. setKnob sets one setting by its catalogue id, and setKnobs sets several in one change. They cover only the plain-valued settings in the module's catalogue.

Both write the same configuration, which getConfig() reads back. A knob id is the setting's path in it, so setKnob(placesModule, placesKnobCatalogue, 'label.color', '#c2185b') changes the label.color that updateConfig({ label: { color: '#c2185b' } }) writes:

Note that the configuration methods don't check values at run time. A value from outside your code, such as JSON.parse output or a model's answer, can reach the map unchecked, so pass it to the knob functions instead.

updateConfig merges one level deep. A nested object you give it replaces the current one. To change one nested field, spread the current part or set its knob:

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

// Settings your code writes: typed, and any setting the module takes
placesModule.updateConfig({ label: { ...placesModule.getConfig()?.label, color: '#c2185b' } });

// Settings held as data: checked against the catalogue, set by path
setKnob(placesModule, placesKnobCatalogue, 'label.color', '#c2185b');
setKnobs(placesModule, placesKnobCatalogue, { 'label.color': '#c2185b', 'label.size': 14 });

• Named setters are for visibility, such as setVisible / isVisible and those of the parts that hide on their own (see Visibility under Appearance vocabulary). The only others are TrafficAreaAnalyticsModule's per-metric setPalette, setColorStops, setHeight and setFilters. A named setter is always set<Setting>.

Saving and replaying a configuration

getConfig() exports a configuration and applyConfig() imports it. A configuration that went through JSON and back into applyConfig holds the same settings and draws the same layers. Keep one to restore a user's map, attach it to a support report, or replay it in a test.

localStorage.setItem('places', JSON.stringify(placesModule.getConfig()));

// Later, on the same module or a new one
placesModule.applyConfig(JSON.parse(localStorage.getItem('places')));

applyConfig doesn't check what it reads back. If the saved settings can come from anywhere other than your own getConfig(), for example an older release or a user's edit, save knob values by id instead and restore them with setKnobs. It checks each value against its catalogue entry and sets none if one is refused:

import { placesKnobCatalogue, setKnobs } from '@tomtom-org/maps-sdk/map';

localStorage.setItem('places', JSON.stringify({ 'label.color': '#c2185b', 'label.size': 14 }));

setKnobs(placesModule, placesKnobCatalogue, JSON.parse(localStorage.getItem('places'))); // RangeError if one is refused

The map effects playground saves its panel this way.

Most module configurations, styling knobs included, are fully JSON. Five modules also take functions or image elements, which JSON can't carry. Each has a type for the part that survives, detailed on its reference page. When you replay, add the rest back in code:

JSON.stringify silently drops a function, but turns an image element into {}, which doesn't replay. To keep the whole configuration serializable, give icon images as URLs, data URIs or SVG text, and a place or waypoint title as a MapLibre expression. POIsModule's icon.categoryIcons also takes image elements, with no type that leaves them out.

const state = JSON.parse(saved); // PlacesModuleSerializableConfig
placesModule.applyConfig({
    ...state,
    connections: { ...state.connections, label: { ...state.connections?.label, title: (connection) => connection.name } },
});

The configuration is what a module draws with, not the data it shows, so replay show() with the data too.

Appearance vocabulary

A concept has the same name on every module that has it. The table lists the shared appearance terms, the rule each follows, and the exact properties that carry it. A module missing from a row doesn't have that concept.

Every setting as data

Each module publishes its display settings as a knob catalogue, static data you can read with no map loaded. A control panel builds its controls from it, and an agent checks values against it. An entry's id is the setting's path in the module's configuration, and never points into a list. A list is one knob of kind colors, enums or offset, or no knob. The kind says which value the entry takes and which fields come with it. The entry type is KnobEntry, and the kinds are KnobKind:

• range is the span a control offers, with the step a slider uses. Its bounds say which ends a value must keep to:

  bounds	A value must be	For example
  hard	between min and max	an opacity, a *Factor
  hard-min	at least min; above max it still applies	a height in metres
  soft	any number	an offset

• default is present where one value holds everywhere. Otherwise, the description says what decides, such as the style, the accent or the global configuration.

• A setting that takes a MapLibre expression, a callback or a structured object stays in the configuration. If a setting also takes an expression, its entry holds the plain-value alternatives, which the module's …KnobValueOf<ID> type names.

• The styling catalogue and the map effects plugin catalogue use the same kinds.

Setting a knob by its id

These functions work with a knob by its catalogue id on every module, including the Styling Foundations module and the map effects plugin's MapEffects:

• setKnob(module, catalogue, id, value) - Sets one setting and keeps every other one. A value its entry refuses changes nothing.

• setKnobs(module, catalogue, values) - Sets several settings, given by id, in one change and one config-change event. It checks every value first, so if its entry refuses one, none is set.

• getKnob(module, catalogue, id) - Reads the value in force: the value you set, otherwise what the module knows it to be (a look knob of a style-owned module reads the loaded style), otherwise the entry's default.

• resetKnob(module, catalogue, id) - Unsets one setting and drops the objects it leaves empty, so a knob you set and then reset leaves the configuration as it was. resetConfig() unsets them all.

• knobEntryOf(catalogue, id) - Reads one entry: kind, range or options, default and description.

• validateKnobValue(entry, value) - Runs the check alone, for a value from a form or a language model.

• validateKnobValue, setKnob and setKnobs throw a RangeError naming the knob and what it expects. The functions that take an id throw an Error for an id the catalogue lacks.

• A literal id types the value it takes. An id held as any string, as in a panel looping over a catalogue, takes any value and is checked when set.

The path is the same for every module, and a knob only ever redraws what its own module draws:

import { getKnob, knobEntryOf, resetKnob, setKnob, trafficFlowKnobCatalogue, validateKnobValue } from '@tomtom-org/maps-sdk/map';

setKnob(trafficFlow, trafficFlowKnobCatalogue, 'filters.roadCategories.values', ['motorway', 'trunk']);
getKnob(trafficFlow, trafficFlowKnobCatalogue, 'visible'); // false until set: the entry's default
resetKnob(trafficFlow, trafficFlowKnobCatalogue, 'filters.roadCategories.values');

const knob = knobEntryOf(trafficFlowKnobCatalogue, 'filters.roadCategories.values'); // kind, range or options, default
validateKnobValue(knob, ['motorway', 'cart track']); // RangeError: … 'cart track' is not

The traffic config playground sets every flow and incidents knob this way, with controls built from the two catalogues.