How to Increase Marker Click or Tap Tolerance Using H.map.HitArea in HERE Maps API for JavaScript

Symptoms
--------

Customers using HERE Maps API for JavaScript may observe one or more of the following:

Map markers are difficult to click or tap, especially on mobile devices.
Marker selection only works when clicking directly on the visible icon.
Touch interactions frequently miss small markers.
Users must repeatedly tap a marker before it is selected.
Marker events are not triggered when clicking slightly outside the icon boundary.
Small marker icons provide a poor user experience due to limited interaction area.

Solution
========

You can increase the clickable or tappable area of a marker by defining a custom hitArea through the H.map.Icon configuration.

A larger hit area improves marker selection accuracy without increasing the visible size of the marker icon.

The H.map.HitArea class supports multiple shape types, including CIRCLE, RECT, POLYGON, and NONE, allowing you to customize how pointer and touch events are detected around a marker.

Applies To
----------

HERE Maps API for JavaScript 3.x
H.map.Marker
H.map.Icon
H.map.HitArea

For more information on these classes and their usage, see H.map.HitArea.

Root Cause
----------

By default, marker interaction is limited to the icon's configured hit-testing area. For small icons, clustered displays, or touch-enabled devices, the default interaction area may require very precise user input. This behavior is expected and can be adjusted through a custom hit area configuration.

Impact
------

Reduced usability of interactive map applications.
Increased likelihood of missed clicks and taps.
Lower interaction accuracy on touchscreens.
Poor customer experience when using small marker icons.

Recommended Action
------------------

Configure a custom hitArea when creating the marker icon.

Supported hit area shapes include:

<br /><br />

// No positive probe area
new H.map.HitArea(H.map.HitArea.ShapeType.NONE);

// Rectangle: [left, top, right, bottom]
new H.map.HitArea(
H.map.HitArea.ShapeType.RECT,
[10, 10, 30, 30]
);

// Circle: [centerX, centerY, radius]
new H.map.HitArea(
H.map.HitArea.ShapeType.CIRCLE,
[20, 20, 10]
);

// Polygon: [x1, y1, x2, y2, x3, y3, ...]
new H.map.HitArea(
H.map.HitArea.ShapeType.POLYGON,
[20, 10, 30, 20, 10, 20]
);

### Example: Circular Hit Area

The following example creates a circular hit area with a radius of 20 pixels:

var marker = new H.map.Marker(
location,
{<br /> icon: new H.map.Icon( <br /> "/Content/images/anchordot.png", <br /> { <br /> size: { w: 20, h: 20 }, <br /> anchor: { x: 10, y: 10 }, <br /> hitArea: new H.map.HitArea( <br /> H.map.HitArea.ShapeType.CIRCLE, <br /> [0, 0, 20] <br /> ) <br /> } <br /> ) <br />}
);

### Radius Selection Guidance

For small marker icons, a radius between 15 and 30 pixels is commonly used to improve selection accuracy.

Consider the following when choosing a radius:

Smaller values provide more precise selection behavior.
Larger values improve usability on touch devices.
Excessively large values may cause nearby markers to be selected unintentionally.

Troubleshooting
---------------

If marker selection does not improve after configuring a hit area:

1. Verify that the hitArea property is applied to the H.map.Icon used by the marker.
2. Confirm that the marker is visible and enabled.
3. Check whether other map objects overlap the marker and intercept events.
4. Validate that the configured radius is large enough for the intended interaction.
5. Test on both desktop and touch-enabled devices.
6. Ensure the icon anchor and hit area coordinates are configured as intended.

Expected Behavior
-----------------

When a custom hit area is configured, users can select the marker by clicking or tapping anywhere within the defined area, including positions outside the visible icon boundaries.

Unexpected Behavior
-------------------

The following may indicate a separate implementation issue:

Clicks or taps inside the configured hit area do not trigger marker events.
Marker interaction fails despite correct hit area configuration.
Event handling is inconsistent across markers using identical settings.

Additional Information
----------------------

For complete API details, refer to the official HERE documentation for:

H.map.HitArea
H.map.Icon
H.map.Marker

Product
-------

HERE Maps API for JavaScript 3.x

Keywords / Tags
---------------

HERE Maps API for JavaScript, H.map.Marker, H.map.Icon, H.map.HitArea, marker click area, marker tap area, marker selection area, marker click tolerance, marker touch sensitivity, custom hit area, circle hit area, increase marker clickable area, marker hit testing, marker not clickable, mobile marker interaction