Repository files navigation

A very fast JavaScript library for geospatial point clustering for browsers and Node.

constindex=newSupercluster({radius:40,maxZoom:16});index.load(points);constclusters=index.getClusters([-180,-85,180,85],2);

Clustering 6 million points in Leaflet:

Supercluster was built to power clustering inMapbox GL JS. Read about how it workson the Mapbox blog.

Install using NPM (npm install supercluster) or Yarn (yarn add supercluster), then:

// import as a ES module in NodeimportSuperclusterfrom'supercluster';// import from a CDN in the browser:importSuperclusterfrom'https://esm.run/supercluster';

Or use it with an ordinary script tag in the browser:

<scriptsrc="https://unpkg.com/supercluster@8.0.0/dist/supercluster.min.js"></script>

Loads an array ofGeoJSON Feature objects. Each feature'sgeometry must be aGeoJSON Point. Once loaded, index is immutable.

For the givenbbox array ([westLng, southLat, eastLng, northLat]) and integerzoom, returns an array of clusters and points asGeoJSON Feature objects.

For a given zoom and x/y coordinates, returns ageojson-vt-compatible JSON tile object with cluster/point features.

Returns the children of a cluster (on the next zoom level) given its id (cluster_id value from feature properties).

Returns all the points of a cluster (given itscluster_id), with pagination support:limit is the number of points to return (set toInfinity for all points),andoffset is the amount of points to skip (for pagination).

Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature) given the cluster'scluster_id.

In addition to the options above, Supercluster supports property aggregation with the following two options:

• map: a function that returns cluster properties corresponding to a single point.
• reduce: a reduce function that merges properties of two clusters into one.

Example of setting up asum cluster property that accumulates the sum ofmyValue property values:

constindex=newSupercluster({map:(props)=>({sum:props.myValue}),reduce:(accumulated,props)=>{accumulated.sum+=props.sum;}});

Themap/reduce options must satisfy these conditions to work correctly:

• map must return a new object, not existingproperties of a point, otherwise it will get overwritten.
• reduce must not mutate the second argument (props).

Install@types/supercluster for the TypeScript type definitions:

npm install @types/supercluster --save-dev

npm install       # install dependenciesnpm run build     # generate dist/supercluster.js and dist/supercluster.min.jsnpm test          # run tests