Marker clustering implemented when more than 50 markers are visible

Rendering more than 50 individual markers simultaneously causes browser performance to degrade visibly — marker overlap makes the map unreadable, and the DOM overhead of 50+ custom elements causes frame drops on mid-range devices. ISO 25010:2011 performance-efficiency classifies this as a resource-utilization defect. For a directory with significant geographic density — urban restaurant guides, event listings, retail locators — unclustered markers make the map's core navigation function unusable at typical zoom levels.

Integrate a clustering library and route all marker rendering through it. The cluster layer must update when filters change — see directory-map-location.map-rendering.markers-sync-filters.

import Supercluster from 'supercluster';

const cluster = new Supercluster({ radius: 40, maxZoom: 16 });
cluster.load(listings.map(l => ({
  type: 'Feature',
  geometry: { type: 'Point', coordinates: [l.lng, l.lat] },
  properties: l
})));

const clusters = cluster.getClusters(mapBbox, currentZoom);
// Render `clusters` array — each item is either a cluster (with point_count) or an individual listing

Mapbox GL JS also supports native source-level clustering via cluster: true on a GeoJSONSource, which offloads the computation to the GL layer.

• ID: directory-map-location.map-rendering.clustering-implemented

• Severity: low

• What to look for: Check whether a clustering library (supercluster, mapbox native clustering, leaflet.markercluster) is integrated. If the project can display >50 markers simultaneously, verify that clusters are rendered instead of individual markers. Zoom in and out to test cluster behavior.

• Pass criteria: When at least 50 markers would be visible at current zoom level, they are grouped into clusters with a count badge. List all marker rendering paths and confirm clustering is applied. Clusters expand into individual markers as you zoom in. Cluster counts are accurate. On pass, report the ratio of clustered vs. unclustered render paths.

• Fail criteria: More than 50 markers render individually on the map with no clustering. Map becomes unresponsive or cluttered. A simple opacity reduction on dense markers does not count as pass.

• Skip (N/A) when: The project never displays more than 50 markers simultaneously, or no map markers exist.

• Detail on fail: "60 listings rendered as individual markers at zoom level 12 with no clustering — map is unresponsive" or "Clustering not implemented; performance degrades visibly with >30 markers"

• Remediation: Use a clustering library. With Mapbox GL JS and Supercluster:

  import Supercluster from 'supercluster';
  
  const cluster = new Supercluster({ radius: 40, maxZoom: 16 });
  cluster.load(listings.map(l => ({ ...l, geometry: { coordinates: [l.lng, l.lat] } })));
  
  const clusters = cluster.getClusters(bbox, zoomLevel);
  // Render clusters and individual markers from the `clusters` array