TomTom Maps for JavaScript
    Preparing search index...

    Type Alias MapEventsConfig

    MapEventsConfig: EventHandlerCursorConfig & {
        cursorOnMap?: CSSCursor;
        cursorOnMouseDown?: CSSCursor;
        longHoverDelayAfterMapMoveMS?: number;
        longHoverDelayOnStillMapMS?: number;
        paddingBoxPx?: number;
        precisionMode?: "box" | "point" | "point-then-box";
    }

    Configuration options for map user event handling.

    Controls how user interactions (clicks, hovers) are detected and processed, including precision modes, cursor styles, and timing behaviors.

    Type Declaration

    • OptionalcursorOnMap?: CSSCursor

      Optional configuration to show custom cursor on the map canvas when not interacting with any handled features.

      Accepts any valid CSS cursor value. This is the default cursor shown when not interacting with any features.

      'default'

      MDN cursor documentation

      // Standard arrow
      cursorOnMap: 'default'

      // Open hand for draggable map
      cursorOnMap: 'grab'

      // Crosshair for measurement tools
      cursorOnMap: 'crosshair'
    • OptionalcursorOnMouseDown?: CSSCursor

      Optional configuration to show custom cursor when clicking (mouse down).

      Accepts any valid CSS cursor value. Provides visual feedback during the click action.

      'grabbing'

      MDN cursor documentation

      // Grabbing hand
      cursorOnMouseDown: 'grabbing'

      // Move cursor
      cursorOnMouseDown: 'move'

      // Custom cursor
      cursorOnMouseDown: 'url(/cursors/drag.png), grabbing'
    • OptionallongHoverDelayAfterMapMoveMS?: number

      Delay to trigger a long-hover event when map has just moved (milliseconds).

      Right after the map has moved, the first long-hover waits longer to prevent unwanted hovers while panning the map. This improves UX by not showing tooltips immediately after map movement.

      Should be higher than longHoverDelayOnStillMapMS.

      800

      // Default delay after map movement
      longHoverDelayAfterMapMoveMS: 800

      // Faster for responsive UI
      longHoverDelayAfterMapMoveMS: 500

      // Longer to avoid accidental triggers
      longHoverDelayAfterMapMoveMS: 1200
    • OptionallongHoverDelayOnStillMapMS?: number

      Delay to trigger a long-hover event when the map was still since the last long hover (milliseconds).

      Once the map is stationary and the user is actively exploring, subsequent long-hovers trigger faster for a more responsive experience.

      Should be lower than longHoverDelayAfterMapMoveMS.

      300

      // Default quick hover
      longHoverDelayOnStillMapMS: 300

      // Instant hover
      longHoverDelayOnStillMapMS: 100

      // Slower for less frequent updates
      longHoverDelayOnStillMapMS: 500
    • OptionalpaddingBoxPx?: number

      Optional padding box to be inserted around the event point, in pixels.

      Ignored if precisionMode is set to "point".

      Guidelines:

      • Desktop: 5-10px for comfortable clicking
      • Mobile/touch: 10-20px for finger-friendly targets
      • Dense data: 3-5px to avoid unintended selections
      5

      // Standard desktop
      paddingBoxPx: 5

      // Mobile-friendly
      paddingBoxPx: 15

      // Precise selection
      paddingBoxPx: 2
    • OptionalprecisionMode?: "box" | "point" | "point-then-box"

      Defines the event coordinates precision mode.

      Modes:

      • box: Features are queried within a padding box around the event point (default)
      • point: Features are queried at the exact event point (most precise)
      • point-then-box: Try point first, then fall back to box if nothing found

      Use Cases:

      • box: Best for general use, easier to click small features
      • point: Precise picking for dense overlapping features
      • point-then-box: Balance between precision and usability
      'box'

      // Easier interaction with padding
      precisionMode: 'box'

      // Exact pixel matching
      precisionMode: 'point'

      // Adaptive approach
      precisionMode: 'point-then-box'

    These settings affect all interactive map modules (places, POIs, routes, etc.). Fine-tuning these values can improve user experience based on your use case.

    // Default configuration for desktop
    const config: MapEventsConfig = {
      precisionMode: 'box',
      paddingBoxPx: 5,
      cursorOnHover: 'pointer',
      longHoverDelayOnStillMapMS: 300
    };

    // Mobile-optimized with larger hit area
    const mobileConfig: MapEventsConfig = {
      precisionMode: 'box',
      paddingBoxPx: 15,  // Larger touch targets
      longHoverDelayAfterMapMoveMS: 1000
    };

    // Precise picking for dense data
    const preciseConfig: MapEventsConfig = {
      precisionMode: 'point',  // Exact pixel matching
      cursorOnHover: 'crosshair'
    };

    Settings

    Member Visibility