Map Slow when Displaying Large Numbers of Clustered Markers with Custom SVG Icons

Symptoms
------------

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

Map panning and zooming become slow when many clustered markers are displayed.
Browser UI freezes temporarily during cluster creation or map interactions.
High CPU usage while rendering clustered markers.
Delayed marker updates after zoom level changes.
Custom SVG marker icons render slowly compared to standard marker icons.
Performance degrades significantly when each marker or cluster uses a unique dynamically generated SVG icon.

Answer
----------

This behavior is expected when a large number of clustered markers require complex or dynamically generated SVG icons. The primary performance cost comes from generating and rendering custom SVG content for many markers during clustering and viewport updates. Performance can be significantly improved by using a lazy icon rendering strategy that initially displays lightweight placeholder icons and renders the final SVG icons only for markers currently visible on the map.

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

HERE Maps API for JavaScript
H.clustering.Provider
Clustered marker visualizations
Applications using custom SVG-based marker or cluster icons

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

Clustering itself is typically efficient, but creating and updating large numbers of unique SVG icons is CPU-intensive. When the map view changes, markers and clusters may require icon updates, causing repeated SVG generation and rendering work. If all icons are generated immediately during clustering initialization, browser rendering can become a bottleneck, resulting in poor responsiveness and visible UI delays.

Impact
----------

Reduced map responsiveness
Increased CPU utilization
Longer cluster initialization times
Noticeable delays during zoom and pan operations
Potential browser freezing in large datasets with complex marker designs

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

### 1. Initialize Clustering with Placeholder Icons

Create a single lightweight icon, such as a transparent or minimal SVG, and reuse it for all cluster and noise markers during initialization. This minimizes rendering work while clustering data is being prepared.

### 2. Render Icons Only for Visible Objects

Listen for map viewport changes and retrieve currently visible clustering objects using H.clustering.Provider.getObjectsWithin().

Example workflow:

1. Detect mapviewchange events.
2. Determine the current viewport area.
3. Call getObjectsWithin() to obtain only markers and clusters visible within that area.
4. Process only those returned objects.

This reduces unnecessary icon generation for off-screen elements.

### 3. Generate Actual Icons Incrementally

Use requestAnimationFrame() to spread icon generation across multiple browser frames.

Recommended approach:

Queue visible markers requiring icon updates.
Render one or a small batch of icons per animation frame.
Apply generated icons individually.
Avoid triggering full cluster refreshes whenever possible.

This prevents long blocking operations and keeps interactions smooth.

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

Clustering works normally with large datasets.
Placeholder icons appear immediately.
Visible markers progressively receive their final SVG icons.
Map interactions remain responsive while icon rendering occurs in the background across multiple frames.

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

The following may indicate an implementation issue rather than normal performance characteristics:

Icons never update from placeholder state.
Visible markers remain permanently unrendered.
Errors occur while calling getObjectsWithin().
Icons disappear after viewport changes.
Repeated full-layer recreation occurs during every render cycle.

Example Optimization Strategy
---------------------------------

1. Create a reusable placeholder icon.
2. Initialize H.clustering.Provider with the placeholder for all marker types.
3. Monitor viewport changes.
4. Retrieve visible objects using getObjectsWithin().
5. Queue icon generation work.
6. Render SVG icons incrementally through requestAnimationFrame().
7. Update only the affected visible markers.

This approach reduces rendering spikes and improves overall user experience when displaying large clustered datasets with complex visual requirements.

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

HERE Maps API for JavaScript, clustering, H.clustering.Provider, getObjectsWithin, requestAnimationFrame, SVG icons, marker performance, cluster performance, map freezing, browser CPU usage, lazy rendering, custom markers, viewport optimization, Web SDK, marker clustering