Module Lifecycle Events

VERSION 0.46.12 PUBLIC PREVIEW

Module lifecycle events let you react to internal state changes within a map module — independent of any user interaction. Two event types are available:

config-change — fired whenever the module’s configuration is mutated (by any setter or applyConfig call).
shown-features — fired by modules that have a show method, immediately after new features are rendered on the map.

Both use the same subscription model: events.on(type, handler) returns an unsubscribe function.

`config-change`

Every module emits config-change when its configuration is updated, regardless of how the change was triggered. This is useful for keeping external UI in sync with module state without coupling UI logic to individual setters.

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

3
const trafficFlow = await TrafficFlowModule.get(map, { visible: false });
4

5
const unsub = trafficFlow.events.on('config-change', (config) => {
6
    console.log('TrafficFlow config updated:', config);
7
    // config reflects the module's full current configuration
8
});
9

10
// Each of these triggers a config-change event:
11
trafficFlow.setVisible(true);
12
trafficFlow.applyConfig({ visible: false });

What triggers `config-change`

Any method that mutates the module’s configuration fires the event. Common examples:

Method	Module
`setVisible(visible)`	All modules
`applyConfig(config)`	All modules
`applyTheme(theme)`	PlacesModule
`moveBeforeLayer(layer)`	GeometriesModule, PlacesModule
`setMode(mode)`	TrafficAreaAnalyticsModule
`setMetric(metric)`	TrafficAreaAnalyticsModule
`filterCategories(filter)`	POIsModule
`setLayerGroupsVisibility(...)`	BaseMapModule

The received config argument reflects the module’s complete current configuration after the change.

Practical example: syncing a toggle button

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

3
const hillshade = await HillshadeModule.get(map, { visible: false });
4
const toggle = document.querySelector('#hillshade-toggle') as HTMLInputElement;
5

6
hillshade.events.on('config-change', (config) => {
7
    // Keep the toggle in sync regardless of who changed visibility
8
    toggle.checked = config?.visible ?? false;
9
});
10

11
toggle.addEventListener('change', () => hillshade.setVisible(toggle.checked));

`shown-features`

The shown-features event fires immediately after a module renders new data on the map. It is only available on modules that have an explicit show method.

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

4
const places = await PlacesModule.get(map);
5

6
const unsub = places.events.on('shown-features', (features) => {
7
    console.log('Places rendered on map:', features);
8
    // features: Place | Place[] | Places
9
    updateResultsPanel(features);
10
});
11

12
const results = await search({ query: 'coffee' });
13
places.show(results); // triggers shown-features

Which modules support `shown-features`

Module	Triggered by	Feature type
`PlacesModule`	`show(places)`	`Place \| Place[] \| Places`
`GeometriesModule`	`show(features)`	`PolygonFeatures`
`RoutingModule`	`showRoutes(routes)` / `showWaypoints(waypoints)`	`{ routes }` or `{ waypoints }`
`TrafficAreaAnalyticsModule`	`show(data)`	`TrafficAreaAnalytics`

Modules that only control existing map data — TrafficFlowModule, TrafficIncidentsModule, HillshadeModule, BaseMapModule, POIsModule — do not emit shown-features.

Practical example: fit map to shown results

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

4
const geometries = await GeometriesModule.get(map);
5

6
geometries.events.on('shown-features', (features) => {
7
    const bbox = bboxFromGeoJSON(features);
8
    if (bbox) {
9
        map.mapLibreMap.fitBounds(bbox, { padding: 40 });
10
    }
11
});

Cleanup

Unsubscribe — remove a single handler

Each events.on() call returns an unsubscribe function. Call it to stop receiving events from that specific handler without affecting any others:

1
const unsubA = places.events.on('config-change', handlerA);
2
const unsubB = places.events.on('config-change', handlerB);
3

4
unsubA(); // removes only handlerA — handlerB keeps firing

`off()` — remove all handlers for a type

events.off(type) clears every handler registered for that event type in one call. Useful during component teardown when you don’t want to track individual unsubscribes:

1
// Clear all config-change listeners at once
2
trafficFlow.events.off('config-change');
3

4
// Clear all shown-features listeners at once
5
places.events.off('shown-features');

off accepts all event types — user interaction types (click, hover, etc.) and module lifecycle types (config-change, shown-features) — so the same teardown pattern works uniformly:

1
// Full cleanup for a component that registered multiple event types
2
function onUnmount() {
3
    places.events.off('click');
4
    places.events.off('hover');
5
    places.events.off('config-change');
6
    places.events.off('shown-features');
7
}

RoutingModule — split events interface

RoutingModule exposes user and module events under separate namespaces rather than a single events.on() surface. Use events.module for lifecycle events:

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

3
const routing = await RoutingModule.get(map);
4

5
// Module lifecycle events — via events.module
6
const unsubConfig = routing.events.module.on('config-change', (config) => {
7
    console.log('Routing config changed:', config);
8
});
9

10
const unsubShown = routing.events.module.on('shown-features', (features) => {
11
    if ('routes' in features) {
12
        console.log('Routes shown:', features.routes);
13
    } else {
14
        console.log('Waypoints shown:', features.waypoints);
15
    }
16
});
17

18
// User interaction events — via events.user.*
19
routing.events.user.mainLines.on('click', (route) => { /* ... */ });
20
routing.events.user.waypoints.on('hover', (waypoint) => { /* ... */ });

Events Overview — All three event categories at a glance
User Interaction Events — Click, hover, long-hover, and contextmenu events
Map Styles — React to style transitions with addStyleChangeHandler
Map Modules — Module initialization and configuration

Module Lifecycle Events

config-change

What triggers config-change