TomTom Maps SDK for JavaScript
This is the documentation of version 1.0.0-rc.1. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    Type Alias MapEventsConfig

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

    The options for how the map handles user events.

    They control how clicks and hovers are detected and processed, including precision modes, cursor styles and timing.

    Type Declaration

    • OptionalcursorOnMap?: CSSCursor

      The cursor to show on the map canvas when not interacting with any handled features.

      Accepts any valid CSS cursor value.

      'default'

      MDN cursor documentation

      // Standard arrow
      cursorOnMap: 'default'

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

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

      The cursor to show while clicking (mouse down).

      Accepts any valid CSS cursor value, which gives visual feedback during the click.

      'grabbing'

      MDN cursor documentation

      // Grabbing hand
      cursorOnMouseDown: 'grabbing'

      // Move cursor
      cursorOnMouseDown: 'move'

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

      The delay, in milliseconds, before a long-hover event fires when the map has just moved.

      The first long hover after the map moves waits longer, so panning doesn't trigger unwanted hovers or show tooltips straight away.

      Set it 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

      The delay, in milliseconds, before a long-hover event fires when the map has stayed still since the last long hover.

      While the map stays still and the user explores, later long hovers fire faster, so the map feels more responsive.

      Set it lower than longHoverDelayAfterMapMoveMS.

      300

      // Default quick hover
      longHoverDelayOnStillMapMS: 300

      // Instant hover
      longHoverDelayOnStillMapMS: 100

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

      The padding box around the event point, in pixels.

      Ignored if precisionMode is set to "point".

      Suggested values:

      • 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"

      The precision mode for the event coordinates.

      • box - Queries features within a padding box around the event point (default).
      • point - Queries features at the exact event point, the most precise mode.
      • point-then-box - Tries point first, then falls back to box if it finds nothing.

      box suits general use, as small features are easier to click. point suits dense, overlapping features. point-then-box balances 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.). Tune them to your use case for a better user experience.

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

    // 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