marker-cluster

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

• load
• loadAsync
• getPoints
• getZoom
• getChildren

Properties

• points
• worker

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