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.
• 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, hillshade — 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 hillshade 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

List of modules

Base map module

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

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

3
const baseMapModule = await BaseMapModule.get(map);
4

5
// Toggle visibility, for the whole base map or for specific layer groups
6
baseMapModule.setVisible(true);
7
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.

1
import { PlacesModule } from '@tomtom-org/maps-sdk/map';
2
import { search } from '@tomtom-org/maps-sdk/services';
3

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

7
// Search and display results
8
const results = await search({ query: 'restaurants near me' });
9
await placesModule.show(results);
10

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

Learn more about Places Module →

POIs module

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

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

3
// Display specific POI categories
4
const poisModule = await POIsModule.get(map, {
5
    filters: {
6
        categories: { show: 'all_except', values: ['ELECTRIC_VEHICLE_STATION'] },
7
    },
8
});

Learn more about POIs Module →

Routing module

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

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

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

7
// Calculate and display route
8
const route = await calculateRoute({
9
    geoInputs,
10
});
11
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.

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

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

6
// Control traffic display
7
trafficFlowModule.setVisible(true);
8

9
// Configure traffic styling
10
trafficFlowModule.filter({
11
    any: [{ showRoadClosures: 'only' }],
12
});

Learn more about Traffic Flow Module →

Traffic incidents module

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

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

3
// Display traffic incidents
4
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
5
    icons: { visible: false },
6
    filters: { any: [{ magnitudes: { show: 'all_except', values: ['minor'] } }] },
7
});

Learn more about Traffic Incidents Module →

Geometries module

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

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

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

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

Learn more about Geometries Module →

Custom GeoJSON module

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

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

3
const customModule = await CustomGeoJSONModule.create(map, {
4
    sources: {
5
        heatmap: { layers: [{ type: 'heatmap' }] }
6
    }
7
});
8

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

Learn more about Custom GeoJSON Module →

Traffic incident overlay module

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

1
import { TrafficIncidentOverlayModule } from '@tomtom-org/maps-sdk/map';
2
import { trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';
3

4
const overlay = await TrafficIncidentOverlayModule.create(map);
5

6
const result = await trafficIncidentDetails({ bbox });
7
await overlay.show(result);

Learn more about Traffic Incident Overlay Module →

Traffic area analytics module

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

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

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

8
await analyticsModule.show(analyticsResult);
9
analyticsModule.setMetric('speed');

Learn more about Traffic Area Analytics Module →

Hillshade module

The HillshadeModule adds terrain elevation shading for topographic visualization.

1
import { HillshadeModule } from '@tomtom-org/maps-sdk/map';
2

3
const hillshadeModule = await HillshadeModule.get(map, {
4
    ensureAddedToStyle: true,
5
});
6

7
// Toggle hillshade visibility
8
hillshadeModule.setVisible(true);

Learn more about Hillshade Module →