marker-cluster

typescript library for point clustering

Usage no npm install needed!

<script type="module">
  import markerCluster from 'https://cdn.skypack.dev/marker-cluster';
</script>

README

marker-cluster

Library for point clustering

Why should I use MarkerCluster?

  • it is really fast
  • it could leverage Worker to avoid freezing while clustering a large amount of points (browsers only)
  • it does not dictate supplied points format
  • format of returned points is customizable

Example

import MarkerCluster from "marker-cluster";

type Point = { lat: number; lng: number };

const points: Point[] = [
  { lat: -31.56391, lng: 147.154312 },
  { lat: -33.718234, lng: 150.363181 },
  { lat: -33.727111, lng: 150.371124 },
  { lat: -33.848588, lng: 151.209834 },
];

const markerCluster = new MarkerCluster<Point>((v) => [v.lng, v.lat], {
  radius: 75,
});

markerCluster.load(points);

// or

await markerCluster.loadAsync(points);

const currPoints = markerCluster.getPoints(
  2,
  -180,
  -85,
  180,
  85,
  (point, lng, lat) => ({ point, lng, lat }),
  (lng, lat, count, clusterId) => ({ count, clusterId, lng, lat })
);

Class: MarkerCluster<T>

Constructor

Methods

Properties

Constructor

constructor(getLngLat: (item: T) => [lng: number, lat: number], options: MarkerClusterOptions)
Name Type Description Default
extent? number tile extent (radius is calculated relative to it) 256
maxZoom? number max zoom level to cluster the points on 16
minZoom? number min zoom level to cluster the points on 0
radius? number cluster radius in pixels 60

Methods

load

load(points: T[]): void

Loads given points

Parameters

Name Type Description
points T[] points for clustering

loadAsync

async loadAsync(points: T[]): Promise<void>

Same to load, but do clustering at another thread

Note: this method use Worker


cleanUp

cleanUp(): void

if loadAsync was called, use this method before MarkerCluster instance has gone


getPoints

getPoints<M, C>(
  zoom: number,
  westLng: number,
  southLat: number,
  eastLng: number,
  northLat: number,
  markerMapper: (point: T, lng: number, lat: number) => M,
  clusterMapper: (lng: number, lat: number, count: number, clusterId: number) => C,
  expand?: number
): (M | C)[]

Parameters

Name Type Description
expand? number for values in range (0..1) considered as percentage, otherwise as absolute pixels value to expand given boundary.

Returns

Array of clusters and points for the given zoom and boundary


getZoom

getZoom(clusterId: number): number

Returns

Zoom level on which the cluster splits into several children, or -1 if it cluster of several points with same coords


getChildren

getChildren(clusterId: number): (T | { clusterId: number; count: number })[]

Properties

points

points?: T[]

points from last executed loadAsync or load


worker

worker?: Worker;

Worker instance, inits at first loadAsync call


License

MIT © Krombik