https://github.com/yuzhva/react-leaflet-markercluster
React wrapper of the official Leaflet.markercluster for react-leaflet
https://github.com/yuzhva/react-leaflet-markercluster
leaflet markercluster react
Last synced: 4 months ago
JSON representation
React wrapper of the official Leaflet.markercluster for react-leaflet
- Host: GitHub
- URL: https://github.com/yuzhva/react-leaflet-markercluster
- Owner: yuzhva
- License: mit
- Created: 2017-01-26T15:27:20.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2025-11-15T10:38:25.000Z (7 months ago)
- Last Synced: 2025-12-07T11:57:46.949Z (6 months ago)
- Topics: leaflet, markercluster, react
- Language: JavaScript
- Homepage: https://yuzhva.github.io/react-leaflet-markercluster/
- Size: 6.24 MB
- Stars: 324
- Watchers: 4
- Forks: 107
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# React leaflet markercluster
[](https://www.npmjs.com/package/react-leaflet-markercluster)
[](https://codeclimate.com/github/YUzhva/react-leaflet-markercluster)
[](https://www.npmjs.com/package/react-leaflet-markercluster)
[](#license)
React wrapper of [Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster)
for [react-leaflet](https://github.com/PaulLeCam/react-leaflet)
**Examples with the Documentation:** https://yuzhva.github.io/react-leaflet-markercluster/
**[CodeSandbox Getting Started](https://codesandbox.io/s/react-leaflet-markercluster-getting-started-9binx)**
# Description
If you are faced with an issue with markers or polygons overlapping during map zooming, or they are
overlapping because they are close to each other - you probably need to group them.
That is what you can do with **react-leaflet-markercluster**.
Just grab your markers or [ClusterableRegions](https://github.com/yuzhva/react-leaflet-markercluster/blob/645bcad7b98e0ecf598c99543373aeeb9c8b301f/.storybook/examples/region.jsx#L13-L45) inside `` component, right after ``:
```javascript
import MarkerClusterGroup from "react-leaflet-markercluster";
;
```
> **Note: Before getting started, please see these useful guides:**
>
> - [Leaflet Quick Start Guide](http://leafletjs.com/examples/quick-start/).
> - [react-leaflet Installation](https://react-leaflet.js.org/docs/en/installation.html).
# Table of Contents
- [Getting started](#getting-started)
- [API](#api)
- [How to run DEV env](#how-to-run-dev-env)
- [Contributors ✨](#contributors-)
- [Contributing](#contributing)
- [License](#license)
# Getting started
**1.** Install package:
```bash
yarn add react-leaflet-markercluster@next # yarn
npm install react-leaflet-markercluster # npm
```
The `react-leaflet-markercluster` requires `leaflet.markercluster` as [`peerDependency`](https://docs.npmjs.com/files/package.json#peerdependencies)
(Leaflet and react-leaflet also should be installed)
```bash
yarn add leaflet.markercluster leaflet react-leaflet # yarn
npm install leaflet.markercluster leaflet react-leaflet # npm
```
**2.** Import **markercluster** and **leaflet** styles:
```javascript
//sass
@import '~leaflet/dist/leaflet.css';
@import '~react-leaflet-markercluster/styles';
//cjs
require('~leaflet/dist/leaflet.css');
require('react-leaflet-markercluster/styles');
//esm
import 'leaflet/dist/leaflet.css'
import 'react-leaflet-markercluster/styles'
```
Or include CSS styles directly to the head of HTML file:
```html
```
**3.** Write some simple `react-leaflet` Map:
```javascript
import { MapContainer, TileLayer, Marker } from "react-leaflet";
;
```
**NOTE:** Remember to add map styles `.markercluster-map { height: 90vh; }`.
**4.** Just put your markers or [ClusterableRegions](https://github.com/yuzhva/react-leaflet-markercluster/blob/645bcad7b98e0ecf598c99543373aeeb9c8b301f/.storybook/examples/region.jsx#L13-L45) inside `` component, right after ``:
```javascript
import MarkerClusterGroup from "react-leaflet-markercluster";
;
```
[More examples with the Documentation](https://yuzhva.github.io/react-leaflet-markercluster/)
[CodeSandbox Getting Started](https://codesandbox.io/s/react-leaflet-markercluster-getting-started-9binx)
# API
Just pass whatever option you need from [All Leaflet.markercluster Options](https://github.com/Leaflet/Leaflet.markercluster#all-options) to `MarkerClusterGroup` as `prop`.
For example:
```javascript
```
or:
```javascript
const createClusterCustomIcon = function (cluster) {
return L.divIcon({
html: `${cluster.getChildCount()}`,
className: 'marker-cluster-custom',
iconSize: L.point(40, 40, true),
});
}
```
P.S: Examples for v1 are available at [CHANGELOG.md](./CHANGELOG.md#v118)
### Event listeners
You are able to add any listener, supported by Leaflet, with simple `on` property prefix.
# How to run DEV env
**1.** Clone the repo:
```bash
git clone https://github.com/YUzhva/react-leaflet-markercluster.git
```
**2.** Install all dependencies:
```bash
yarn install --no-lockfile # yarn
npm install # npm
```
**3.** Start the server:
```bash
yarn dev # yarn
npm run dev # npm
```
**4.** After starting the server, storybook should automatically open the following address:
```
http://localhost:8080/
```
# Contributors ✨
Thanks goes to these wonderful people:
Avatars rendered by [contributors-img](https://contributors-img.web.app).
**Special thanks to:**
- [@webcarrot](https://github.com/webcarrot) for [react-leaflet v2 support](https://github.com/yuzhva/react-leaflet-markercluster/issues/71#issuecomment-403071677)
- [@CodeCutterUK](https://github.com/CodeCutterUK) for [react-leaflet v3 support](https://github.com/yuzhva/react-leaflet-markercluster/pull/124)
# Contributing
All sources are placed in the `./src` folder:
**1.** Fork the repo.
**2.** Edit `react-leaflet-markercluster.js` plugin or `style.scss` style files.
**3.** Commit your changes and open Pull Request.
:beer: **Thank you for contribution** :beer:
# UMD
UMD builds are available on [unpkg](https://unpkg.com/):
```html
```
# License
MIT License, see [LICENSE](https://github.com/YUzhva/react-leaflet-markercluster/blob/master/LICENSE) file.