Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/googlemaps/js-markerclusterer
Create and manage clusters for large amounts of markers
https://github.com/googlemaps/js-markerclusterer
clustering google google-maps googlemaps javascript maps marker-clustering markers utility-library
Last synced: about 1 month ago
JSON representation
Create and manage clusters for large amounts of markers
- Host: GitHub
- URL: https://github.com/googlemaps/js-markerclusterer
- Owner: googlemaps
- License: apache-2.0
- Created: 2021-09-28T17:41:53.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-29T22:00:37.000Z (about 2 months ago)
- Last Synced: 2024-07-30T09:21:11.031Z (about 2 months ago)
- Topics: clustering, google, google-maps, googlemaps, javascript, maps, marker-clustering, markers, utility-library
- Language: TypeScript
- Homepage: https://googlemaps.github.io/js-markerclusterer/
- Size: 9.01 MB
- Stars: 207
- Watchers: 20
- Forks: 81
- Open Issues: 72
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Google Maps JavaScript MarkerClusterer
[](https://www.npmjs.com/package/@googlemaps/markerclusterer)
[](https://codecov.io/gh/googlemaps/js-markerclusterer)
[](https://github.com/semantic-release/semantic-release)
[](https://github.com/apps/in-solidarity)
## Description
The library creates and manages per-zoom-level clusters for large amounts of markers.
[**Try the demo**](https://googlemaps.github.io/js-markerclusterer/public/defaults/)
See the [history section](#history) and [migration section](#migration) for how this library relates to [@google/markerclusterer][@google/markerclusterer] and [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus].
## Install
Available via npm as the package [@googlemaps/markerclusterer](https://www.npmjs.com/package/@googlemaps/markerclusterer).
```
npm i @googlemaps/markerclusterer
```
Alternativly you may add the umd package directly to the html document using the unpkg link.
```html
```
When adding via unpkg, the `MarkerClusterer` can be accessed at `markerClusterer.MarkerClusterer`.
#### TypeScript
This library uses the official TypeScript typings for Google Maps Platform, [@types/google.maps](https://www.npmjs.com/package/@types/google.maps).
```sh
npm i -D @types/google.maps
```
## Documentation
The [reference documentation](https://googlemaps.github.io/js-markerclusterer/) is generated from the TypeScript definitions.
## Examples
```js
import { MarkerClusterer } from "@googlemaps/markerclusterer";
// use default algorithm and renderer
const markerCluster = new MarkerClusterer({ map, markers });
```
View the package in action:
- [Algorithm Comparisons](https://googlemaps.github.io/js-markerclusterer/public/algorithms) - This example demonstrates the different algorithms. Please note that spacing and many other options can be changed for each algorithm.
- [Renderer Usage](https://googlemaps.github.io/js-markerclusterer/public/renderers) - This example demonstrates different renderers similar to the image below.
## History
This library has a heritage in [@google/markerclusterer][@google/markerclusterer] and [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus], originally made available on [code.google.com](https://code.google.com/archive/) and then transferred to GitHub at https://github.com/googlemaps/v3-utility-library. The following is an approximate timeline.
- 201X - [@google/markerclusterer][@google/markerclusterer] was created.
- 201X - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was created.
- 2019 - Libraries were published to NPM.
- 2019 - [@google/markerclusterer][@google/markerclusterer] was deprecated for [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus].
- 2020 - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was refactored to TypeScript.
- 2020 - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was moved to a separate repository.
- 2021 - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was rewritten as [@googlemaps/markerclusterer (**new**)][@googlemaps/markerclusterer].
- TBD - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] is deprecated for [@googlemaps/markerclusterer (**new**)][@googlemaps/markerclusterer].
## Migration
The API of [@googlemaps/markerclusterer][@googlemaps/markerclusterer] has changed in a number of ways from [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus].
- The `MarkerClusterer` class now accepts an `algorithm` and `renderer` parameter to allow for more flexibility. The interface looks like the following:
```js
{
algorithm?: Algorithm;
map?: google.maps.Map;
markers?: google.maps.Marker[];
renderer?: Renderer;
onClusterClick?: onClusterClickHandler;
}
```
- The `MarkerClusterer` accepts a single options argument instead of positional parameters.
- The traditional `GridAlgorithm` is still supported, **but is not the default**. The default is [supercluster](https://www.npmjs.com/package/supercluster) which uses [k-d trees](https://en.wikipedia.org/wiki/K-d_tree) for improved performance.
- Styling of clusters has been simplifed and moved to the renderer interface.
- The `MarkerClusterer` class is still an instance of `google.maps.OverlayView`, but uses `google.maps.Marker`s instead of `google.maps.Overlay` to render the clusters. This solves issues related to the usage of map panes and click handlers.
- @googlemaps/markerclusterer supports Marker and Map [a11y improvements](https://cloud.google.com/blog/products/maps-platform/improved-accessibility-maps-javascript-api).
[@googlemaps/markerclustererplus]: https://www.npmjs.com/package/@googlemaps/markerclustererplus
[@google/markerclusterer]: https://www.npmjs.com/package/@google/markerclusterer
[@googlemaps/markerclusterer]: https://www.npmjs.com/package/@googlemaps/markerclusterer