NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #3006 most downloaded on npm
A very fast geospatial point clustering library.
Latest stable
9.1.0
Last release 2 months ago
03 Sep 2026
Ships unpredictably
gaps range from 3 weeks to 3.3 years
Nearly every release is documented
notes for 27 of 28 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
28 releases · first in 2016
Drag across the ruler to compare, or tap a release to open it.
Adds a flat tile envelope matching geojson-vt v5's getTileRaw, and moves TypeScript declarations into the package.
Adds a flat tile envelope matching geojson-vt v5's getTileRaw, and moves TypeScript declarations into
the package.
getTileRaw(z, x, y) returns the same tiles as getTile, but with each feature's coordinates
inline — {type: 4, x, y, tags} instead of {type: 1, geometry: [[x, y]], tags}. Every clustered
feature is a single point, so this is geojson-vt's raw envelope narrowed to its lone-point variant,
and consumers that unwrap geometry[0] immediately can skip two array allocations per feature.
getTile is unchanged.@types/supercluster if you have it
installed.The bundled declarations cover the same surface as @types/supercluster@7.1.3, with three
differences:
@types users: types are named exports rather than members of a merged
Supercluster namespace. Replace Supercluster.Options<P, C> with an
import type {Options} from 'supercluster'. Using Supercluster<P, C> itself in type position
still works. This matches how geojson-vt's declarations are shaped.tags are typed | null | undefined. Supercluster passes each input feature's properties
through verbatim, so tags is null when the input had properties: null and undefined when it
omitted the member — both need a guard before use. The old declarations claimed tags was always
present.load() accepts MultiPoint features as well as Point, matching the support added in v9.0.0.Your coding agent can read these notes before it upgrades. Set up the MCP server →
Radically optimize memory footprint and performance — on a sample 1M points index, Supercluster now uses 94% less transient allocation, 57% lower peak
maxZoom at 30 (it wasn't practical to use it on higher zooms anyway).MultiPoint features. #263Fix an error when creating an empty index (after load([])). #225
Fix an error when creating an empty index (after load([])). #225
⚡ Drastically reduce memory footprint (by up to 60%) and improve clustering performance by ~15-20%. #223
kdbush dependency to v4.Fix handling of non-integer zoom values in methods like getClusters(). #199
Fix handling of non-integer zoom values in methods like getClusters(). #199
Avoid creating new objects for same clusters across zooms, improving memory footprint and making sure the same clusters have the same cluster_id acros
Avoid creating new objects for same clusters across zooms, improving memory footprint and making sure the same clusters have the same cluster_id across zoom levels. #190
Fix a bug where coordinates of unclustered points were snapping to a grid on higher zoom levels. #176
Fix a bug where coordinates of unclustered points were snapping to a grid on higher zoom levels. #176
Fix fround fallback on IE11 so that the v7.1.1 small radius bugfix is effective there too.
Fix fround fallback on IE11 so that the v7.1.1 small radius bugfix is effective there too.
Fix a bug where identical points sometimes wouldn't cluster on higher zooms given a small radius.
Fix a bug where identical points sometimes wouldn't cluster on higher zooms given a small radius.
Added minPoints option for the minimum number of points to form a cluster (2 by default).
Added minPoints option for the minimum number of points to form a cluster (2 by default).
Added generateId option to generate numeric ids (feature.id) for input features that don't have it.
generateId option to generate numeric ids (feature.id) for input features that don't have it.generateId.Slightly improved performance of map/reduce by avoiding redundant map calls. #131
Slightly improved performance of map/reduce by avoiding redundant map calls. #131
Fixed a bug introduced in v6.0.0 where some aggregated cluster properties were calculated incorrectly.
Fixed a bug introduced in v6.0.0 where some aggregated cluster properties were calculated incorrectly.
⚠️ Breaking: removed initial option of the map/reduce functionality. Now Supercluster uses the first mapped item of the cluster as the initial value:
⚠️ Breaking: removed initial option of the map/reduce functionality. Now Supercluster uses the first mapped item of the cluster as the initial value:
// before
value = initial;
reduce(value, a);
reduce(value, b);
...
// after
value = a;
reduce(value, b);
...
In most cases, you can simply remove the initial option and things will work. There are some exceptions where you'd need to update your map function to make up for lack of initial, but they should be rare.
⚠️ breaking: changed the API entry point to new Supercluster(...) in place of supercluster(...). This makes it more in line with idiomatic modern ES,
new Supercluster(...) in place of supercluster(...). This makes it more in line with idiomatic modern ES, and also more flexible (i.e. you can extend the class). #109getClusterExpansionZoom not returning the right result on maxZoom. #106main entry point remains a ES5-compatible UMD build.Fix a build issue that prevented v4.1.0 from being published to NPM.
Fix a build issue that prevented v4.1.0 from being published to NPM.
Fix a bug where getClusters didn't return correct results with a -180..180 bbox.
Fix a bug where getClusters didn't return correct results with a -180..180 bbox.
Exposed Supercluster as a proper ES module.
Exposed Supercluster as a proper ES module.
Fixed a bug that could cause supercluster to get stuck in an infinite loop when given unwrapped bbox values in getClusters. #80 #73
Fixed a bug that could cause supercluster to get stuck in an infinite loop when given unwrapped bbox values in getClusters. #80 #73
Fixed getClusters queries with the bbox crossing the date line.
Fixed getClusters queries with the bbox crossing the date line.
Added default export for better ES6 modules / transpiler support.
Added default export for better ES6 modules / transpiler support.
⚠️ Removed clusterZoom argument from getLeaves, getChildren and getClusterExpansionZoom methods — it's now encoded into cluster_id numbers, so there's
clusterZoom argument from getLeaves, getChildren and getClusterExpansionZoom methods — it's now encoded into cluster_id numbers, so there's no longer a need to track it separately.cluster_id numbers compared to previous releases.getLeaves to properly handle features with null properties.null geometries (supercluster will ignore them instead of throwing an error).cluster_id will now result in a descriptive error.Added cluster properties aggregation through initial, map and reduce options. #36
initial, map and reduce options. #36getChildren method for getting children of a cluster on the next zoom. #31getLeaves method for getting points of a cluster with pagination support. #19getClusterExpansionZoom for getting the zoom where cluster expands (useful for "click to zoom" feature). #33Fixed clipping of clusters near the date line. #16
Improved performance by at least 2 times by switching to a faster spatial index (kdbush).
kdbush).Fixed a bug in getTile when requesting tiles higher than maxZoom
getTile when requesting tiles higher than maxZoomRenamed numPoints cluster property to point_count
numPoints cluster property to point_countnumPointsH cluster property to point_count_abbreviatedNothing published for this version
One column per quarter.