# supercluster

> A very fast geospatial point clustering library.

Latest version **9.1.0** (published 2026-09-03) · ISC license · 0 weekly downloads

## Install

```sh
npm install supercluster
pnpm add supercluster
yarn add supercluster
bun add supercluster
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 9.1.0 |
| Published | 2026-09-03 |
| First published | 2016-01-18 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 71.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2372 |
| Author | Vladimir Agafonkin |
| Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user, mbx-npm-ci-staging, mbx-npm-ci-production, mbx-npm-01-production, mbx-npm-02-production, mbx-npm-03-production, mbx-npm-04-production, mbx-npm-05-production, mbx-npm-06-production, mbx-npm-07-production, mbx-npm-08-production, mbx-npm-09-production, mbx-npm-02-staging, mbx-npm-advanced-actions-staging, mbx-npm-advanced-actions-production, mourner |
| Keywords | clustering, geospatial, markers |

## Links

- npm: https://www.npmjs.com/package/supercluster
- Repository: https://github.com/mapbox/supercluster
- Homepage: https://github.com/mapbox/supercluster#readme
- Issues: https://github.com/mapbox/supercluster/issues
- npm.io page: https://npm.io/package/supercluster

## Dependencies (2)

- [kdbush](https://npm.io/package/kdbush.md) ^4.1.0
- [@types/geojson](https://npm.io/package/@types/geojson.md) ^7946.0.16

## Recent versions

- 9.1.0 (latest) — 2026-09-03
- 9.0.0 — 2026-08-10
- 8.0.1 — 2023-04-27
- 8.0.0 — 2023-04-26
- 7.1.5 — 2022-04-05
- 7.1.4 — 2021-10-11
- 7.1.3 — 2021-03-30
- 7.1.2 — 2021-01-19
- 7.1.1 — 2021-01-19
- 7.1.0 — 2020-06-02
- 7.0.0 — 2019-11-05
- 6.0.2 — 2019-07-23
- 6.0.1 — 2019-01-24
- 6.0.0 — 2019-01-17
- 5.0.0 — 2018-11-22
- … 13 more at https://npm.io/package/supercluster/versions

## README

# supercluster [![Simply Awesome](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects) [![Node](https://github.com/mapbox/supercluster/actions/workflows/node.yml/badge.svg)](https://github.com/mapbox/supercluster/actions/workflows/node.yml)

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

```js
const index = new Supercluster({radius: 40, maxZoom: 16});
index.load(points);

const clusters = index.getClusters([-180, -85, 180, 85], 2);
```

Clustering 6 million points in Leaflet:

![clustering demo on an interactive Leaflet map](https://cloud.githubusercontent.com/assets/25395/11857351/43407b46-a40c-11e5-8662-e99ab1cd2cb7.gif)

Supercluster was built to power clustering in [Mapbox GL JS](https://www.mapbox.com/mapbox-gljs). Read about how it works [on the Mapbox blog](https://blog.mapbox.com/clustering-millions-of-points-on-a-map-with-supercluster-272046ec5c97).

## Install

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

```js
// import as a ES module in Node
import Supercluster from 'supercluster';

// import from a CDN in the browser:
import Supercluster from 'https://esm.run/supercluster';
```

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

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

## Methods

#### `load(points)`

Loads an array of [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) objects. Each feature's `geometry` must be a [GeoJSON Point](https://tools.ietf.org/html/rfc7946#section-3.1.2) or [MultiPoint](https://tools.ietf.org/html/rfc7946#section-3.1.3) — a MultiPoint is clustered as an individual point per coordinate, each inheriting the feature's `properties` and `id`. Once loaded, index is immutable.

#### `getClusters(bbox, zoom)`

For the given `bbox` array (`[westLng, southLat, eastLng, northLat]`) and integer `zoom`, returns an array of clusters and points as [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) objects.

#### `getTile(z, x, y)`

For a given zoom and x/y coordinates, returns a [geojson-vt](https://github.com/mapbox/geojson-vt)-compatible JSON tile object with cluster/point features, or `null` where there's no data.

#### `getTileRaw(z, x, y)`

The same tile, but with each feature flat &mdash; `{type: 4, x, y, tags}`, coords inline instead of
wrapped in a nested `geometry` array. Every clustered feature is a single point, so this is exactly
geojson-vt's `getTileRaw` shape narrowed to its lone-point (`type: 4`) variant.

#### `getChildren(clusterId)`

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

#### `getLeaves(clusterId, limit = 10, offset = 0)`

Returns all the points of a cluster (given its `cluster_id`), with pagination support:
`limit` is the number of points to return (set to `Infinity` for all points),
and `offset` is the amount of points to skip (for pagination).

#### `getClusterExpansionZoom(clusterId)`

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

## Options

| Option     | Default | Description                                                       |
|------------|---------|-------------------------------------------------------------------|
| minZoom    | 0       | Minimum zoom level at which clusters are generated.               |
| maxZoom    | 16      | Maximum zoom level at which clusters are generated. Capped at 30. |
| minPoints  | 2       | Minimum number of points to form a cluster.                       |
| radius     | 40      | Cluster radius, in pixels.                                        |
| extent     | 512     | (Tiles) Tile extent. Radius is calculated relative to this value. |
| nodeSize   | 64      | Size of the KD-tree leaf node. Affects performance.               |
| log        | false   | Whether timing info should be logged.                             |
| generateId | false   | Whether to generate ids for input features in vector tiles.       |

### Property map/reduce options

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 a `sum` cluster property that accumulates the sum of `myValue` property values:

```js
const index = new Supercluster({
    map: (props) => ({sum: props.myValue}),
    reduce: (accumulated, props) => { accumulated.sum += props.sum; }
});
```

The `map`/`reduce` options must satisfy these conditions to work correctly:

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

## TypeScript

Type declarations ship with the library; remove `@types/supercluster` if you have it. The types those
declarations exposed as namespace members are now named exports:

```ts
import Supercluster from 'supercluster';
import type {Options, PointFeature, ClusterFeature, Tile, RawTile} from 'supercluster';
```

## Developing Supercluster

```
npm install       # install dependencies
npm run build     # generate dist/supercluster.js and dist/supercluster.min.js
npm test          # run tests
```

---
_Source: https://npm.io/package/supercluster · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._