Registry / web-framework / react-leaflet-cluster

react-leaflet-cluster

JSON →
library4.1.3jsnpmunverified

react-leaflet-cluster is a plugin that integrates Leaflet.markercluster functionality into React-Leaflet applications. It provides a `MarkerClusterGroup` component for easily creating animated marker clusters on maps. The current stable version is 4.1.3, with recent updates (v4.1.0) focusing on performance improvements for layer additions. The library maintains an active release cadence, frequently updating to support the latest versions of its core peer dependencies, including React 19, React-Leaflet 5, and Leaflet 1.9.x. Key differentiators include robust TypeScript support, explicit compatibility with Next.js by requiring manual CSS imports, and a strong focus on keeping up with its ecosystem's major version bumps, making it a reliable choice for modern React mapping projects requiring marker clustering capabilities.

web-frameworkhttp-networking
npm install react-leaflet-cluster
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · REACT-LEAFLET-CLUS
R
react-leaflet-cluster
web-frameworkjavascriptv4.1.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MarkerClusterGroup
✓ import MarkerClusterGroup from 'react-leaflet-cluster'
✗ import { MarkerClusterGroup } from 'react-leaflet-cluster'
This is a default export, typically imported without curly braces.
CSS Styles
✓ import 'react-leaflet-cluster/dist/assets/MarkerCluster.css' import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'
✗ require('react-leaflet-cluster/dist/assets/MarkerCluster.css')
CSS imports must be manual since v3.0.0 to prevent Next.js build issues. CommonJS `require` for CSS is generally not recommended in modern React builds.
L (Leaflet global)
✓ import L from 'leaflet'
✗ const L = require('leaflet')
Used for configuring Leaflet's global defaults, such as marker icons, especially after v3.1.0 where automatic icon configuration was removed.

This example demonstrates how to set up a basic Leaflet map with `react-leaflet-cluster`, including required CSS imports and manual default marker icon configuration. It generates 500 random markers to showcase the clustering functionality.

import React from 'react'; import { MapContainer, TileLayer, Marker } from 'react-leaflet'; import MarkerClusterGroup from 'react-leaflet-cluster'; import L from 'leaflet'; import 'leaflet/dist/leaflet.css'; import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'; import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'; // Configure default marker icons (required since v3.1.0) delete (L.Icon.Default as any).prototype._getIconUrl; L.Icon.Default.mergeOptions({ iconRetinaUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png', iconUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png', shadowUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png' }); const position = [51.505, -0.09]; // London coordinates function App() { // Generate a large number of random markers for clustering demonstration const markers = Array.from({ length: 500 }, (_, i) => ({ position: [ position[0] + (Math.random() - 0.5) * 0.1, position[1] + (Math.random() - 0.5) * 0.2 ], key: `marker-${i}` })); return ( <MapContainer center={position} zoom={10} style={{ height: '100vh', width: '100%' }}> <TileLayer attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors' url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" /> <MarkerClusterGroup chunkedLoading> {markers.map((marker) => ( <Marker key={marker.key} position={marker.position} /> ))} </MarkerClusterGroup> </MapContainer> ); } export default App;
Debug
Known issues
breakingVersion 4.0.0 introduced significant peer dependency updates. Projects must upgrade to React 19, React-Leaflet 5, Leaflet 1.9.0, and @react-leaflet/core 3.0.0 or newer.
fix
Ensure your `package.json` peer dependencies match:
```json
"react": "^19.0.0",
"react-dom": "^19.0.0",
"leaflet": "^1.9.0",
"react-leaflet": "^5.0.0",
"@react-leaflet/core": "^3.0.0"
```
affects: >=4.0.0
breakingSince v3.0.0, CSS files for MarkerClusterGroup are no longer automatically imported. You must manually import them to ensure proper styling, especially to avoid issues in environments like Next.js.
fix
Add these lines to your main component or entry file:
```typescript
import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'
import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'
```
affects: >=3.0.0
breakingAs of v3.1.0, the package no longer automatically configures Leaflet's default marker icons. If you use default Leaflet markers, their icons will appear broken without manual configuration.
fix
Add the following configuration to your application's entry point or map component:
```typescript
import L from 'leaflet';
delete (L.Icon.Default as any).prototype._getIconUrl;
L.Icon.Default.mergeOptions({
  iconRetinaUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png',
  iconUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png',
  shadowUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png',
});
```
affects: >=3.1.0
gotchaVersion 4.1.0 introduced a performance optimization that buffers `addLayer()` calls and flushes them in a microtask. While an improvement, developers should be aware of this asynchronous behavior if relying on immediate layer state updates within the same event loop tick.
fix
No direct fix needed; this is a performance improvement. If immediate synchronous access to recently added layers within the cluster group is critical, ensure operations are scheduled after the current microtask queue has flushed or observe relevant cluster events.
affects: >=4.1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading '_getIconUrl')
Leaflet's default marker icons are not correctly configured after v3.1.0, typically due to a missing or misconfigured `L.Icon.Default.mergeOptions` call.
fix
Implement the manual icon configuration as shown in the warnings section for versions >=3.1.0, ensuring Leaflet can find the default marker assets.
MarkerClusterGroup component renders unstyled or incorrectly styled clusters (e.g., plain squares instead of styled circles)
The required CSS files for MarkerClusterGroup are not imported, which is necessary since v3.0.0.
fix
Add the necessary CSS imports to your entry file or map component:
`import 'react-leaflet-cluster/dist/assets/MarkerCluster.css';
import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css';`
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
This general React error can occur in older `react-leaflet-cluster` versions (pre-v2.1.0) due to a Hooks order problem or mismatched React/React-Leaflet versions.
fix
Upgrade to `react-leaflet-cluster` v2.1.0 or newer and ensure your `react` and `react-leaflet` peer dependencies are compatible with the installed version.
Upgrade
Version history
4.1.3latest on npm
Audit
Dependencies
@react-leaflet/corerequiredCore component for React-Leaflet integrations.
leafletrequiredUnderlying map library for all Leaflet functionality.
reactrequiredPrimary UI library for building components.
react-domrequiredDOM-specific render methods for React.
react-leafletrequiredReact components for Leaflet maps.
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/akursat/react-leaflet-cluster ↗
packagehttps://www.npmjs.com/package/react-leaflet-cluster ↗
homepagehttps://akursat.gitbook.io/marker-cluster/ ↗
react-leaflet-cluster — npm install react-leaflet-cluster · libregistry