Map modules

Map Modules are self-contained extensions that add specialized functionality to a TomTomMap instance.

Each module provides focused capabilities for different mapping needs — from displaying traffic information to handling user-generated content — while following a consistent pattern for initialization, configuration, and lifecycle management that makes them easy to integrate and use together.

Key features

• Composition: Modules can be combined to work together seamlessly. Whether a given module type can be instantiated more than once on the same map depends on who owns the layers it controls — see Types of modules below.
• Data management: Modules handle their own data sources and rendering
• Style integration: Modules automatically integrate with map styles and themes
• Statefulness: Modules maintain their own state and configuration independently. Modules restore their state when the map style changes.
• One configuration surface: every module takes its configuration at creation and through applyConfig(config) (a whole configuration, replacing the current one), updateConfig(partial) (changes the given properties and keeps the rest, the same on every module) and resetConfig(); getConfig() reads it back and events.on('config-change', …) reports every change. See Changing a setting.
• Smart event handling: Modules provide their own event systems for user interactions with seamless mapping to the original typed data.
• Service integration: Seamless integration with TomTom services for added data such as places, routes and geometries
• Lazy loading: Modules are loaded only when needed for optimal performance

Types of modules

There are two types of modules in the TomTom Maps SDK, depending on who owns the sources and layers the module controls. Ownership decides both the factory you call and how many instances make sense on one map.

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

These modules do not display data of their own. They control sources and layers that the map style already provides — the base map, POI symbols, the traffic tile layers, the terrain elevation — under source and layer IDs that are fixed and global to the style.

A style-owned module is therefore a shared controller, not a piece of content. get() is a lookup, and quite literally so: the SDK keeps one instance per map, so calling it twice returns the same module. Two components can each ask for the terrain without coordinating, and neither has to hoist a shared reference.

Calling get(map) with no configuration is a plain accessor — it changes nothing. Calling it with a configuration applies that configuration to the instance that already exists.

To handle events for only part of what a style-owned module covers, scope the events rather than creating a second module — see Scoped events.

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

These modules bring their own data. They add the GeoJSON sources, layers and sprite images they need and own them for their whole lifetime, with every identifier suffixed per instance.

Instances are therefore fully independent: create() builds a new module every time, and stacking several of them on one map — one set of places per search, one route per plan — is a supported thing to do. Nothing is shared or reused between them.

Per-module reference

Who owns what

Everything visible on the map has exactly one owner, and the owner follows from who owns the layers. Every module has knobs of its own: the style-owned modules decide whether the loaded style's layers show, the Styling module how the style draws them, and each data-owned instance everything about the layers it adds itself. The dashed lines are the only places a knob reaches past its module: the base-map group toggles write through BaseMapModule, and the data-owned modules read the accent as their default colour.

In detail:

Two consequences:

• The rows do not cross. Styling knobs never write a data-owned module's layers, and a data-owned module never restyles the base map under it: recolouring a route is RoutingModule configuration, recolouring the roads it runs on is colors.roadMajor. The accent and the borrowed looks are read, not written.
• The first two rows meet at three points:
  • Whole groups. A basemap.<group> toggle knob (buildings.footprints and buildings.3d for the two building groups, roads.shields for roadShields) writes through BaseMapModule, and styling.get reads the layers back, so it agrees with baseMap.isVisible(…). The later call wins, across a setStyle too: baseMap.setVisible over a group removes that group's knob from styling.getConfig(), and a knob set afterwards lands on top of the base map's record.
  • Layers inside a module's layers. pois.microMarkers among the POIs, and roads.arrows, roads.restricted, roads.underConstruction and roads.exitNumbers among the base-map roads, can only hide what their module shows. false hides those layers; true never shows them while POIsModule or BaseMapModule hides them; the module showing its layers again keeps a knob's false; and unsetting the knob leaves the layers as the module has them.
  • POI filters. pois.zoomShift rewrites the POI layer filters that the POIsModule filters.categories setting narrows, and the two compose in either order.

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

Changing a setting

Every setting changes through three calls each module has: applyConfig(config) replaces the whole configuration, updateConfig(partial) changes the top-level properties it is given, and setKnob sets one setting by its catalogue id.

• updateConfig merges one level deep. A nested object it is given replaces the one there, so to change one nested field, spread the current part or set its knob:

  placesModule.updateConfig({ label: { ...placesModule.getConfig()?.label, color: '#c2185b' } });
  setKnob(placesModule, placesKnobCatalogue, 'label.color', '#c2185b');
  

• Named setters are for visibility: setVisible / isVisible and 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() is the export and applyConfig() the import: a module's configuration that went through JSON, given back to applyConfig, holds the same configuration 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')));

Most modules' configurations are JSON whole, styling's knobs included. Five modules also take functions or image elements, which JSON cannot carry. Each has a type for the part that survives, which its reference page details; a replay adds the rest back in code:

JSON.stringify drops a function without a trace, but turns an image element into {}, which does not replay. Give icon images as URLs, data URIs or SVG text, and a place or waypoint title as a MapLibre expression, to keep the whole configuration serializable. POIsModule's icon.categoryIcons takes image elements too, with no type to leave them out.

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

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

Appearance vocabulary

A concept has one 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 does not have that concept.

Every setting as data

A module's display settings are also published as a knob catalogue: static data, readable with no map loaded, that a control panel builds its controls from and an agent checks a value against. An entry's id is the setting's path in the module's configuration, where a number indexes a list (filters.any.0), and its kind says which value it 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. Without it, the description says what decides: the style, the accent, the global configuration.

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

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

Setting a knob by its id

setKnob sets one setting by its catalogue id and keeps every other one; a value its entry refuses changes nothing. validateKnobValue is the check alone, for a value from a form or a language model. Both throw a RangeError naming the knob and what it expects.

The path is the same for every module, the Styling module's and the map effects plugin's own set included, and a knob only ever redraws what its own module draws:

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

setKnob(trafficFlow, trafficFlowKnobCatalogue, 'filters.any.0.roadCategories.values', ['motorway', 'trunk']);

const knob = trafficFlowKnobCatalogue.find(({ id }) => id === 'filters.any.0.roadCategories.values');
validateKnobValue(knob, ['motorway', 'cart track']); // RangeError: … 'cart track' is not

The Styling Module's own set runs the same check. The traffic config playground sets every flow and incidents knob this way, from controls built off the two catalogues.

List of modules

Base map module

A BaseMapModule provides visibility and events for layer groups of the base map.

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

const baseMapModule = await BaseMapModule.get(map);

// Toggle visibility, for the whole base map or for specific layer groups
baseMapModule.setVisible(true);
baseMapModule.setVisible(false, { layerGroups: { mode: 'include', names: ['borders', 'buildings2D'] } });

Learn more about Base Map Module →

Places module

A PlacesModule handles search results visualization and place information display.

import { PlacesModule } from '@tomtom-org/maps-sdk/map';
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';

// Initialize places module
const placesModule = await PlacesModule.create(map);

// Search and display results
const results = await discoverPlaces({ query: 'restaurants near me' });
await placesModule.show(results);

// Handle place interactions — `events.places` is the pins alone, typed as Place
placesModule.events.places.on('click', (place) => {
    console.log('Selected place:', place.properties.title);
});

Learn more about Places Module →

POIs module

A POIsModule controls the display and events for Points of Interest with category-based filtering and styling.

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

// Display specific POI categories
const poisModule = await POIsModule.get(map, {
    filters: {
        categories: { show: 'all-except', values: ['CHARGING_LOCATION'] },
    },
});

Learn more about POIs Module →

Routing module

A RoutingModule controls the display of routes, waypoints, and navigation instructions, and user events on such parts.

import { RoutingModule } from '@tomtom-org/maps-sdk/map';
import { calculateRoute } from '@tomtom-org/maps-sdk/services';

// Initialize routing module
const routingModule = await RoutingModule.create(map);

// Calculate and display route
const route = await calculateRoute({
    locations: [
        [4.9041, 52.3676], // Amsterdam
        [4.4777, 51.9244]  // Rotterdam
    ],
});
await routingModule.showRoutes(route);

Learn more about Routing Module →

Traffic flow module

The TrafficFlowModule displays real-time traffic flow information with color-coded speed indicators.

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

// Add traffic flow visualization
const trafficFlowModule = await TrafficFlowModule.get(map);

// Control traffic display
trafficFlowModule.setVisible(true);

// Show road closures only
trafficFlowModule.updateConfig({
    filters: { any: [{ showRoadClosures: 'only' }] },
});

Learn more about Traffic Flow Module →

Traffic incidents module

The TrafficIncidentsModule shows traffic incidents like accidents, road closures, and construction.

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

// Display traffic incidents
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
    icons: { visible: false },
    filters: { any: [{ magnitudes: { show: 'all-except', values: ['minor'] } }] },
});

Learn more about Traffic Incidents Module →

Geometries module

The GeometriesModule displays custom geometric data like polygons, lines, and markers.

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

// Initialize geometries module
const geometryModule = await GeometriesModule.create(map);

const geometryToSearch = await geometryData({ geometries: location });
await geometryModule.show(geometryToSearch);

Learn more about Geometries Module →

Reachable ranges module

The ReachableRangesModule displays what calculateReachableRanges returns: each band titled from its budget, each origin's bands nested, coloured from the map.

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

const rangesModule = await ReachableRangesModule.create(map, { fillStyle: 'outline' });
await rangesModule.show(await calculateReachableRanges([10, 20].map((value) => ({ origin, budget: { type: 'timeMinutes', value } }))));

Learn more about displaying reachable ranges →

Custom GeoJSON module

The CustomGeoJSONModule renders your own GeoJSON data with typed sources, clustering, custom images, and style-change restoration.

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

const customModule = await CustomGeoJSONModule.create(map, {
    sources: {
        heatmap: { layers: [{ type: 'heatmap' }] }
    }
});

await customModule.show(heatmapData, 'heatmap');

Learn more about Custom GeoJSON Module →

Traffic incident details module

The TrafficIncidentDetailsModule renders a specific set of incidents you fetched yourself, rather than the live vector-tile layer.

import { TrafficIncidentDetailsModule } from '@tomtom-org/maps-sdk/map';
import { trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';

const incidentDetailsModule = await TrafficIncidentDetailsModule.create(map);

const result = await trafficIncidentDetails({ bbox });
await incidentDetailsModule.show(result);

Learn more about Traffic Incident Details Module →

Traffic area analytics module

The TrafficAreaAnalyticsModule visualizes aggregated traffic statistics for an area as a hexgrid, square grid, or heatmap.

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

const analyticsModule = await TrafficAreaAnalyticsModule.create(map, {
    displayMode: 'hexgrid-3d',
    activeMetric: 'congestionLevel',
});

await analyticsModule.show(analyticsResult);
analyticsModule.updateConfig({ activeMetric: 'speed' });

Learn more about Traffic Area Analytics Module →

Terrain module

The TerrainModule draws the relief of the elevation data: hillshade shading, and the map surface raised in 3D.

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

const terrain = await TerrainModule.get(map, { hillshade: true });

// Raise the surface in 3D, for a pitched camera
terrain.setElevationEnabled(true);

Learn more about Terrain Module →