gistda-sphere-react

MarkerCluster

Show thousands of points as markers, grouped into numbered clusters that split apart as users zoom in

<MarkerCluster> groups nearby points into numbered cluster markers, and renders the other points with your renderMarker, so every point keeps its React icon, popup and events. Clusters split apart as users zoom in, and only markers in or near the visible area are rendered, so thousands of points stay fast.

Click a cluster to zoom in to its points.

import { type Location, Marker, MarkerCluster, SphereMap } from "gistda-sphere-react";

interface Station {
  id: string;
  name: string;
  position: Location;
}

function StationMap({ stations }: { stations: Station[] }) {
  return (
    <SphereMap style={{ height: 500 }}>
      <MarkerCluster
        getPosition={(station) => station.position}
        items={stations}
        renderMarker={(station) => (
          <Marker position={station.position} title={station.name} />
        )}
      />
    </SphereMap>
  );
}

Props

PropTypeDefaultDescription
itemsT[]requiredThe points. Memoize large arrays, since a new array is clustered again.
getPosition(item) => LocationrequiredWhere each item is.
renderMarker(item, index) => ReactNoderequiredRenders a point that isn't in a cluster, usually as a <Marker>. index is the item's position in items.
renderCluster(cluster) => ReactNodeblue bubble with the countIcon content of a cluster marker.
onClusterClick(cluster) => voidzoom inReplaces the default of zooming in to the cluster's points.
radiusnumber60How close points must be to cluster, in screen pixels.
minPointsnumber2Fewest points that form a cluster.
maxZoomnumber16Points never cluster above this zoom.

Clusters

renderCluster and onClusterClick receive a Cluster:

FieldDescription
countHow many points the cluster holds.
itemsThe points themselves.
positionThe points' average position, where the cluster marker is.
boundThe points' bounding box, { minLon, minLat, maxLon, maxLat }.
keyAn ID that stays the same while the cluster keeps its first point and size.

Cluster icons are React marker icons, so you can style them freely. This example lists a cluster's points instead of zooming in:

import { Marker, MarkerCluster } from "gistda-sphere-react";
import { useState } from "react";

const [selected, setSelected] = useState<Station[]>([]);

<MarkerCluster
  getPosition={(station) => station.position}
  items={stations}
  onClusterClick={(cluster) => setSelected(cluster.items)}
  renderCluster={(cluster) => <span className="cluster-badge">{cluster.count}</span>}
  renderMarker={(station) => <Marker position={station.position} title={station.name} />}
/>

How it works

Points are grouped again when the zoom level changes. Whole zoom levels are used, so clusters stay put while users pan or zoom a little. Above maxZoom, every point gets its own marker.

Only clusters and markers in or near the visible area are rendered, and the others appear as users pan toward them. A marker that leaves that area unmounts, so React state inside it resets when it comes back.

For hundreds of thousands of points, cluster in MapLibre with a <Layer> style instead. The GPU draws the points, so it's faster, but it shows circles rather than React markers.

On this page