Events

The TomTom Maps SDK provides three distinct event systems, each addressing a different layer of interaction:

User interaction events

User interaction events fire when the map's end users interact with features rendered by a module — clicks, hovers, long-hovers, and right-clicks. The SDK enhances MapLibre's raw mouse events with built-in hover state management, configurable precision, and automatic mapping back to the original typed data.

// Most modules expose user interaction events via events.on(...)
placesModule.events.on('click', (feature, lngLat) => { /* ... */ });
trafficModule.events.on('hover', (feature, lngLat) => { /* ... */ });
baseMap.events.on('contextmenu', (feature, lngLat) => { /* ... */ });

// RoutingModule is namespaced differently
routing.events.click((feature, lngLat) => { /* ... */ });

User Interaction Events guide →

Module lifecycle events

Module lifecycle events fire when a module's internal state changes — either because configuration was updated or because new features were rendered on the map. These events are independent of any user gesture.

• config-change — emitted by every module whenever its config is mutated (via applyConfig, setVisible, or any module-specific setter).
• shown-features — emitted by modules that have a show method (PlacesModule, GeometriesModule, RoutingModule, TrafficAreaAnalyticsModule), immediately after features are displayed.

// Fires on any config mutation
trafficFlow.events.on('config-change', (config) => {
    syncToggle(config?.visible);
});

// Fires after any of the module's show operations; the payload says which
places.events.on('shown-features', (features) => {
    if ('places' in features) fitMapToResults(features.places);
});

Module Lifecycle Events guide →

Style change events

Style change events let you hook into the setStyle transition lifecycle — before the old style is torn down and after the new style is fully loaded. Use these to preserve custom MapLibre layers, sync UI state (e.g. dark mode), or run async teardown/setup logic.

map.addStyleChangeHandler({
    onStyleAboutToChange: () => {
        saveCustomLayers();
    },
    onStyleChanged: () => {
        restoreCustomLayers();
        syncDarkModeClass();
    },
});

Style Change Events section →

MapLibre events

Because TomTomMap exposes the underlying MapLibre instance via map.mapLibreMap, the full MapLibre Map event API is also available — load, moveend, zoom, styledata, and many more.

map.mapLibreMap.on('moveend', () => {
    console.log('Viewport changed:', map.mapLibreMap.getBounds());
});

Prefer the SDK's own event systems for anything involving SDK-managed features. Use map.mapLibreMap events for low-level map lifecycle hooks that the SDK does not expose directly.

Choosing the right event