User Interaction Events

VERSION 0.41.1 PUBLIC PREVIEW

The User Interaction Events system in the TomTom Maps SDK provides enhanced event handling capabilities that build upon MapLibre’s native events. This system simplifies complex user interactions and provides consistent event handling across different map elements and modules, enabling rich interactive mapping experiences.

import { Place, TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { BaseMapModule, PlacesModule, TomTomMap, TrafficIncidentsModule } from '@tomtom-org/maps-sdk/map';
import { reverseGeocode, search } from '@tomtom-org/maps-sdk/services';
import { LngLat, MapGeoJSONFeature, Marker, NavigationControl, Popup } from 'maplibre-gl';
import './style.css';
import { API_KEY } from './config';

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY });

(async () => {
    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            center: [-0.12634, 51.50276],
            zoom: 14,
        },
    });
    const popUp = new Popup({
        closeButton: true,
        closeOnClick: true,
        closeOnMove: true,
        offset: 15,
        className: 'sdk-example-popup',
    });
    let isMarkerVisible = false;
    const revGeocodingMarker = new Marker({ color: '#df1b12' });

    const showTrafficPopup = (topFeature: MapGeoJSONFeature, lngLat: LngLat) => {
        const { properties } = topFeature;

        const incidentSeverity: Record<number, string> = {
            3: 'major',
            2: 'moderate',
            1: 'minor',
        };

        popUp
            .setOffset(5)
            .setHTML(
                `
        <div id="traffic-incident-popup">
        <h3>Traffic incident</h3>
        <b id="traffic-incident-road-type">Road type</b> ${topFeature.properties.road_category}<br />
        <b id="traffic-incident-magnitude">Magnitude</b> ${incidentSeverity[properties.magnitude]} <br />
        <b id="traffic-incident-delay">Delay</b> ${Math.floor(properties.delay / 60)} m ${
            properties.delay % 60
        } s</b> <br />
        </div>
        `,
            )
            .setLngLat(lngLat)
            .addTo(map.mapLibreMap);
    };

    const initTrafficIncidents = async () => {
        (await TrafficIncidentsModule.get(map, { visible: true })).events.on('long-hover', showTrafficPopup);
    };

    const showPlacesPopUp = (topFeature: Place, lngLat: LngLat) => {
        const { address, poi } = topFeature.properties;

        if (isMarkerVisible) {
            revGeocodingMarker.remove();
        }

        new Popup({
            closeButton: true,
            closeOnClick: true,
            closeOnMove: true,
            offset: 15,
            className: 'sdk-example-popup',
        })
            .setHTML(
                `
            <div id="place-popup">
            <h3 id="place-name">${poi?.name}</h3>
            <b id="place-address"> Address: </b> ${address.freeformAddress}
            <br />
            ${poi?.phone ? `<b> Phone: </b> ${poi?.phone}` : ''}
            <div id="sdk-example-popup-tags">
            ${poi?.categories?.map((category) => `<span class="sdk-example-popup-tags-item">${category}</span>`)}
            </div>
            </div> 
            `,
            )
            .setLngLat(lngLat)
            .addTo(map.mapLibreMap)
            .once('close', () => (isMarkerVisible = true));
    };

    const initPlacesModule = async () => {
        const placesModule = await PlacesModule.get(map);

        const places = await search({
            query: 'pharmacy',
            limit: 35,
            boundingBox: map.getBBox(),
        });

        placesModule.show(places);
        placesModule.events.on('click', showPlacesPopUp);
    };

    const showBasemapPopup = async (_: any, lnglat: LngLat) => {
        const { properties } = await reverseGeocode({ position: [lnglat.lng, lnglat.lat] });
        revGeocodingMarker.setLngLat(lnglat).addTo(map.mapLibreMap);

        if (!isMarkerVisible) {
            new Popup({
                closeButton: true,
                closeOnClick: true,
                closeOnMove: true,
                offset: 6,
                className: 'sdk-example-popup-basemap',
            })
                .setHTML(
                    `
                <div id="sdk-example-popup-basemap">
                ${
                    properties.address.freeformAddress
                        ? ` <h4 id="sdk-example-popup-basemap-address">${properties.address.freeformAddress}</h4> <hr class="sdk-example-hr" />`
                        : ''
                }
                    <div id="sdk-example-popup-lnglat">
                        <span> ${lnglat.lng.toFixed(5)}, ${lnglat.lat.toFixed(5)}</span>
                    </div>
                </div> 
                `,
                )
                .setLngLat(lnglat)
                .addTo(map.mapLibreMap);
            isMarkerVisible = true;
        } else {
            revGeocodingMarker.remove();
            isMarkerVisible = false;
        }
    };

    const initBaseMapModule = async () => {
        const baseModule = await BaseMapModule.get(map);
        // Listening hover events on Basemap module to remove traffic popups.
        baseModule.events.on('hover', () => popUp.isOpen() && popUp.remove());
        baseModule.events.on('click', showBasemapPopup);
    };

    map.mapLibreMap.addControl(new NavigationControl());
    map.mapLibreMap.on('dragstart', () => {
        revGeocodingMarker.remove();
        isMarkerVisible = false;
    });

    await initBaseMapModule();
    await initPlacesModule();
    await initTrafficIncidents();
})();

Open Sandbox

Event System Architecture

The TomTom SDK’s event system addresses common MapLibre event handling challenges while maintaining full compatibility with the underlying MapLibre event infrastructure. This dual-layer approach provides both familiar MapLibre patterns and enhanced TomTom-specific functionality.

Enhanced Event Capabilities

Problems Solved by TomTom Events:

Complex hover implementation: MapLibre hover events require manual timing, state management, and precision handling
Event conflicts: Multiple interactive sources can interfere with each other without proper coordination
Data transformation: Raw MapLibre events need conversion to application-specific formats with relevant context
Precision issues: Accurate event detection with appropriate tolerance is difficult to implement consistently

TomTom SDK Solutions:

Unified event API: Consistent event handling patterns across all SDK modules through dedicated events objects
Built-in hover support: Automatic hover detection with configurable delays, thresholds, and state management
Conflict resolution: Smart event routing between different map modules and layers prevents interference
Rich data integration: Events include relevant TomTom data and contextual information automatically

Module-Specific Event Systems

Each TomTom module provides its own dedicated event system through an events object, eliminating the need to work directly with MapLibre events for module-specific interactions:

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

3
// Each module exposes its own events object
4
const placesModule = await PlacesModule.get(map);
5
const trafficModule = await TrafficIncidentsModule.get(map);
6
const routesModule = await RoutingModule.get(map);
7

8
// Access module-specific events through the events object
9
placesModule.events.on('click', handlePlaceClick);
10
trafficModule.events.on('hover', handleTrafficHover);
11
routesModule.events.on('click', handleRouteClick);

Basic Event Handling

Standard MapLibre Event Integration

The SDK maintains full compatibility with MapLibre events for general map interactions:

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

3
const map = new TomTomMap({ mapLibre: { container: 'map' } });
4

5
// Standard MapLibre events for general map interaction
6
map.mapLibreMap.on('click', (event) => {
7
    console.log('Map clicked at:', event.lngLat);
8
});
9

10
map.mapLibreMap.on('moveend', () => {
11
    const bounds = map.mapLibreMap.getBounds();
12
    console.log('New map bounds:', bounds);
13
});

TomTom Module Event Handling

Places Module Events

The Places Module provides rich event handling for place interactions through its dedicated events system:

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

3
const placesModule = await PlacesModule.get(map);
4

5
// Use the module's events object for TomTom-specific interactions
6
placesModule.events.on('click', (feature, lngLat) => {
7
    console.log('Place clicked:', feature.properties.name);
8
    console.log('Click coordinates:', lngLat);
9
    displayPlaceDetails(feature.properties);
10
});
11

12
placesModule.events.on('hover', (feature) => {
13
    console.log('Place hovered:', feature.properties.name);
14
    showPlacePreview(feature.properties);
15
});

Traffic Module Events

Traffic incidents and flow data provide specialized event handling for traffic-related interactions:

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

3
const trafficIncidentsModule = await TrafficIncidentsModule.get(map);
4

5
// Traffic-specific events with enriched data
6
trafficIncidentsModule.events.on('click', (feature, lngLat) => {
7
    displayTrafficIncident({
8
        type: feature.properties.type,
9
        severity: feature.properties.severity,
10
        description: feature.properties.description,
11
        delay: feature.properties.delay,
12
        location: lngLat
13
    });
14
});
15

16
trafficModule.events.on('long-hover', (feature, lngLat) => {
17
    showTrafficTooltip(feature.properties, lngLat);
18
});

Routing Module Events

Route interactions provide detailed information about route segments and waypoints:

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

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

5
routesModule.events.on('click', (feature) => {
6
    console.log('Route clicked:', feature.properties.routeId);
7
    console.log('Route segment:', feature.properties.segmentIndex);
8
    showRouteDetails(feature.properties);
9
});

Advanced Event Types

Hover Events

The SDK introduces sophisticated hover detection that addresses the complexity of implementing reliable hover functionality with MapLibre. Traditional hover implementation requires managing mouse enter/leave events, dealing with timing issues, and handling state management across different map features.

Hover Event Challenges:

Timing complexity: Raw mouse events require debouncing and timing management
State management: Tracking which features are currently hovered requires careful state handling
Performance concerns: Frequent mouse events can impact application performance
Cross-layer conflicts: Multiple interactive layers can interfere with hover detection

TomTom Hover Solutions: The SDK provides automatic hover detection with built-in timing, state management, and performance optimization:

1
// Standard hover: Immediate response to mouse enter
2
placesModule.events.on('hover', (feature) => {
3
    showQuickPreview(feature.properties);
4
});

Long-Hover Events

Long-hover events are particularly valuable for displaying detailed information without cluttering the interface with immediate popups. This pattern is ideal for progressive disclosure interfaces where users can get quick information by hovering briefly, or detailed information by maintaining hover focus.

Long-Hover Implementation Benefits:

Prevents accidental triggers: Users must maintain focus for a specified duration
Reduces UI noise: Detailed information appears only when users demonstrate intent
Improves performance: Expensive operations (like API calls) are triggered only after sustained interest
Enhanced UX: Creates a natural progression from quick glance to detailed exploration

Configurable Long-Hover Timing: The long-hover delay is configurable to match your application’s UX requirements:

1
// Long hover with default timing (typically 800ms)
2
trafficModule.events.on('long-hover', (feature, lngLat) => {
3
    fetchDetailedTrafficInfo(feature.properties.incidentId)
4
        .then(details => showDetailedIncident(details, lngLat));
5
});

Event Timing and Configuration

Different modules may have different timing requirements based on the type of interaction and data complexity:

1
// Example of how timing might vary by module type
2
// (Note: Actual configuration methods may vary by implementation)
3
trafficModule.events.on('long-hover', (feature) => {
4
    // Triggered after longer delay for complex traffic data
5
    displayComprehensiveTrafficAnalysis(feature.properties);
6
});
7

8
placesModule.events.on('hover', (feature) => {
9
    // Triggered quickly for simple place information
10
    showPlaceBasicInfo(feature.properties);
11
});

Event Data Structure

Enhanced Event Payloads

TomTom module events provide enriched data compared to raw MapLibre events.

Modules where service data is added (places, routes, geometries) will map their user events to the original added data.

1
placesModule.events.on('click', (feature, lngLat, allFeatures, source) => {
2
    // feature: GeoJSON feature with TomTom-specific properties
3
    console.log('Feature data:', feature.properties);
4

5
    // lngLat: Precise click coordinates
6
    console.log('Click location:', lngLat);
7

8
    // allFeatures: All features at the event location (array of MapGeoJSONFeature)
9
    console.log('All features at location:', allFeatures.length);
10

11
    // source: Source and layer configuration for the feature
12
    console.log('Source:', source);
13
});

Event Configuration

Map-Level Configuration (MapEventsConfig)

Configure global event behavior when initializing the map through the events option. These settings affect all interactive modules and layers:

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

3
const map = new TomTomMap({
4
    mapLibre: {
5
        container: 'map'
6
    },
7
    events: {
8
        precisionMode: 'box',
9
        paddingBoxPx: 10,
10
        cursorOnHover: 'pointer',
11
        longHoverDelayAfterMapMoveMS: 800,
12
        longHoverDelayOnStillMapMS: 300
13
    }
14
});

Precision Configuration

Control how accurately events detect features:

1
// Standard: Easier clicking with 5px tolerance (default)
2
events: {
3
    precisionMode: 'box',
4
    paddingBoxPx: 5
5
}
6

7
// Mobile: Larger touch targets
8
events: {
9
    precisionMode: 'box',
10
    paddingBoxPx: 15
11
}
12

13
// Precise: Exact pixel matching for dense data
14
events: {
15
    precisionMode: 'point'
16
}

Hover Timing Configuration

Adjust long-hover delays to match your UX requirements:

1
// Responsive: Quick tooltips after map settles
2
events: {
3
    longHoverDelayAfterMapMoveMS: 500,  // After panning
4
    longHoverDelayOnStillMapMS: 200     // Subsequent hovers
5
}
6

7
// Conservative: Prevent accidental triggers
8
events: {
9
    longHoverDelayAfterMapMoveMS: 1200,
10
    longHoverDelayOnStillMapMS: 500
11
}

Cursor Styling

Customize cursor appearance for different interaction states:

1
events: {
2
    cursorOnMap: 'grab',           // Default cursor
3
    cursorOnHover: 'pointer',      // When hovering features
4
    cursorOnMouseDown: 'grabbing'  // During click/drag
5
}

Module-Level Configuration (EventHandlerConfig)

Individual modules can override cursor behavior for their specific features:

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

3
const placesModule = await PlacesModule.get(map, {
4
    events: {
5
        cursorOnHover: 'help'  // Custom cursor for places
6
    }
7
});
8

9
// Different cursor for different modules
10
const trafficModule = await TrafficIncidentsModule.get(map, {
11
    events: {
12
        cursorOnHover: 'crosshair'  // Different cursor for traffic
13
    }
14
});

Handling Events on the Rest of the Map

Detecting Clicks Outside Interactive Features

When building interactive maps, you often need to detect when users interact with the base map itself—areas outside of your custom features like places, routes, or traffic incidents. This is essential for:

Clearing selections: Deselecting features when users click empty map areas
Resetting UI state: Hiding popups or info panels when focus moves away
Triggering map-wide actions: Performing reverse geocoding on arbitrary map locations
Managing interaction modes: Switching between different interaction states

The BaseMapModule provides a solution for detecting these “rest of the map” interactions through its event system.

Using BaseMapModule for Background Interactions

The BaseMapModule manages all fundamental map layers (roads, buildings, land, water, etc.). By using its event handlers, you can detect user interactions with the underlying map:

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

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

5
// Detect clicks on the base map
6
baseMap.events.on('click', (feature, lngLat) => {
7
    console.log('Map clicked at:', lngLat);
8
    clearAllSelections();
9
    performReverseGeocoding(lngLat);
10
});
11

12
// Detect hovers over the base map
13
baseMap.events.on('hover', (feature, lngLat) => {
14
    console.log('Hovering over:', feature.properties);
15
    hideAllPopups();
16
});

Separating Interactive and Background Layers

For more sophisticated applications, you can create separate BaseMapModule instances to differentiate between interactive features and the “rest” of the map. This pattern is particularly useful when you want certain map layers to be interactive while treating others as background.

Pattern: Interactive vs. Background Modules

This approach uses layer group filtering to create two distinct modules:

Interactive module: Handles specific layer groups you want users to interact with
Background module: Handles everything else, representing the “rest of the map”

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

3
// Define which layer groups should be interactive
4
const interactiveLayerGroups = ['roadLines', 'roadLabels', 'buildings3D'];
5

6
// Module for interactive features
7
const interactiveLayers = await BaseMapModule.get(map, {
8
    layerGroupsFilter: {
9
        mode: 'include',
10
        names: interactiveLayerGroups
11
    }
12
});
13

14
// Module for the rest of the map (background)
15
const restOfTheMap = await BaseMapModule.get(map, {
16
    layerGroupsFilter: {
17
        mode: 'exclude',
18
        names: interactiveLayerGroups
19
    },
20
    events: {
21
        cursorOnHover: 'default'  // Keep default cursor on background
22
    }
23
});
24

25
// Handle interactive layer clicks
26
interactiveLayers.events.on('click', (feature, lngLat) => {
27
    console.log('Interactive feature clicked:', feature.properties);
28
    showFeatureDetails(feature);
29
});
30

31
// Handle background clicks
32
restOfTheMap.events.on('click', (feature, lngLat) => {
33
    console.log('Background clicked');
34
    clearAllSelections();
35
});

Practical Example: Clearing Selections

A common use case is clearing feature selections when users click outside interactive elements:

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

3
const placesModule = await PlacesModule.get(map);
4
const baseMap = await BaseMapModule.get(map, {
5
    events: { cursorOnHover: 'default' }
6
});
7

8
let selectedPlace = null;
9

10
// Select places on click
11
placesModule.events.on('click', (feature, lngLat) => {
12
    selectedPlace = feature;
13
    highlightPlace(feature);
14
    showPlaceDetails(feature);
15
});
16

17
// Clear selection when clicking the base map
18
baseMap.events.on('click', () => {
19
    if (selectedPlace) {
20
        selectedPlace = null;
21
        clearHighlights();
22
        hidePlaceDetails();
23
    }
24
});

See the Rest of the Map Click example for a complete working implementation of this pattern.

Cursor Behavior for Background Interactions

When handling background map interactions, it’s important to configure the cursor appropriately to provide proper visual feedback to users.

Why Set cursorOnHover: 'default'?

By default, when hovering over any interactive module features, the cursor changes to indicate interactivity (typically to 'pointer'). However, for background map layers, you usually want to maintain the default cursor to signal that these elements are not primary interactive targets:

1
// Background module with default cursor
2
const restOfTheMap = await BaseMapModule.get(map, {
3
    layerGroupsFilter: {
4
        mode: 'exclude',
5
        names: ['places', 'traffic']
6
    },
7
    events: {
8
        cursorOnHover: 'default'  // Prevents pointer cursor on hover
9
    }
10
});

Cursor Configuration Patterns:

1
// Pattern 1: Interactive features with pointer, background with default
2
const interactiveFeatures = await BaseMapModule.get(map, {
3
    layerGroupsFilter: { mode: 'include', names: ['roadLines'] },
4
    events: { cursorOnHover: 'pointer' }  // Shows as clickable
5
});
6

7
const background = await BaseMapModule.get(map, {
8
    layerGroupsFilter: { mode: 'exclude', names: ['roadLines'] },
9
    events: { cursorOnHover: 'default' }  // Shows as not interactive
10
});
11

12
// Pattern 2: Map-wide configuration with module overrides
13
const map = new TomTomMap({
14
    mapLibre: {
15
        container: 'map'
16
    },
17
    events: {
18
        cursorOnHover: 'pointer'  // Default for all modules
19
    }
20
});
21

22
// Override for background to use default cursor
23
const background = await BaseMapModule.get(map, {
24
    events: { cursorOnHover: 'default' }
25
});

Complete Example: Multi-Module Interaction

Here’s a comprehensive example showing how different modules work together with background detection:

1
import {
2
    BaseMapModule,
3
    PlacesModule,
4
    TrafficIncidentsModule
5
} from '@tomtom-org/maps-sdk/map';
6

7
// Initialize modules
8
const placesModule = await PlacesModule.get(map);
9
const trafficModule = await TrafficIncidentsModule.get(map);
10
const baseMap = await BaseMapModule.get(map, {
11
    events: { cursorOnHover: 'default' }
12
});
13

14
let activePopup = null;
15

16
// Places interactions
17
placesModule.events.on('click', (feature, lngLat) => {
18
    activePopup = showPopup('place', feature, lngLat);
19
});
20

21
// Traffic interactions
22
trafficModule.events.on('click', (feature, lngLat) => {
23
    activePopup = showPopup('traffic', feature, lngLat);
24
});
25

26
// Base map hover - clear popups when moving to background
27
baseMap.events.on('hover', () => {
28
    if (activePopup) {
29
        activePopup.remove();
30
        activePopup = null;
31
    }
32
});
33

34
// Base map click - perform reverse geocoding
35
baseMap.events.on('click', async (feature, lngLat) => {
36
    if (activePopup) {
37
        activePopup.remove();
38
        activePopup = null;
39
    }
40

41
    const result = await reverseGeocode({
42
        position: [lngLat.lng, lngLat.lat]
43
    });
44

45
    showAddressInfo(result, lngLat);
46
});

Event Priority and Layer Order

Event priority is determined by layer rendering order - whichever layer is rendered on top receives the event first. This follows the natural visual stacking of map elements.

How Event Priority Works:

The module whose layers are rendered highest (top-most) in the layer stack receives the event:

1
const placesModule = await PlacesModule.get(map);
2
const baseMap = await BaseMapModule.get(map);
3

4
// Click on a place marker: placesModule receives the event
5
// Click on a road: baseMap receives the event

Multiple Module Instances:

When creating multiple instances of the same module type, later instances are typically rendered on top:

1
const roads = await BaseMapModule.get(map, {
2
    layerGroupsFilter: { mode: 'include', names: ['roadLines'] }
3
});
4

5
const buildings = await BaseMapModule.get(map, {
6
    layerGroupsFilter: { mode: 'include', names: ['buildings3D'] }
7
});
8

9
// buildings module is on top - receives events first for overlapping areas

Key Principles:

Layer-based priority: Top-most visible layer receives the event
No event bubbling: Events don’t propagate to lower layers
Visual hierarchy: What users see on top gets the interaction
Module independence: Each module’s events operate separately

Services Integration

Reverse Geocoding - Use user click events to trigger reverse geocoding and display address information
Search Services - Handle user interactions to trigger place searches and display results
Geocoding - Process user input events to geocode addresses and show locations

Rest of the Map Click - Simple example showing how to detect clicks on places vs. the rest of the map
Map Events - Comprehensive map event handling examples with different interaction patterns
Pin Interaction - Interactive markers with click and hover events
Reverse Geocoding with Map Display - Click events triggering reverse geocoding with visual feedback
Places Customize - Custom event handling for place interactions

Places Module - Handle user interactions with places and markers
Routing Module - Manage user interactions with routes and route segments
Traffic Incidents - Handle user interactions with traffic data and incidents