{"id":11740,"library":"react-leaflet-cluster","title":"React Leaflet Marker Cluster","description":"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.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/akursat/react-leaflet-cluster","tags":["javascript","react","leaflet","marker-cluster","cluster","map","react-leaflet-v4","typescript"],"install":[{"cmd":"npm install react-leaflet-cluster","lang":"bash","label":"npm"},{"cmd":"yarn add react-leaflet-cluster","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-leaflet-cluster","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core component for React-Leaflet integrations.","package":"@react-leaflet/core","optional":false},{"reason":"Underlying map library for all Leaflet functionality.","package":"leaflet","optional":false},{"reason":"Primary UI library for building components.","package":"react","optional":false},{"reason":"DOM-specific render methods for React.","package":"react-dom","optional":false},{"reason":"React components for Leaflet maps.","package":"react-leaflet","optional":false}],"imports":[{"note":"This is a default export, typically imported without curly braces.","wrong":"import { MarkerClusterGroup } from 'react-leaflet-cluster'","symbol":"MarkerClusterGroup","correct":"import MarkerClusterGroup from 'react-leaflet-cluster'"},{"note":"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.","wrong":"require('react-leaflet-cluster/dist/assets/MarkerCluster.css')","symbol":"CSS Styles","correct":"import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'\nimport 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'"},{"note":"Used for configuring Leaflet's global defaults, such as marker icons, especially after v3.1.0 where automatic icon configuration was removed.","wrong":"const L = require('leaflet')","symbol":"L (Leaflet global)","correct":"import L from 'leaflet'"}],"quickstart":{"code":"import React from 'react';\nimport { MapContainer, TileLayer, Marker } from 'react-leaflet';\nimport MarkerClusterGroup from 'react-leaflet-cluster';\nimport L from 'leaflet';\n\nimport 'leaflet/dist/leaflet.css';\nimport 'react-leaflet-cluster/dist/assets/MarkerCluster.css';\nimport 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css';\n\n// Configure default marker icons (required since v3.1.0)\ndelete (L.Icon.Default as any).prototype._getIconUrl;\nL.Icon.Default.mergeOptions({\n  iconRetinaUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png',\n  iconUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png',\n  shadowUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png'\n});\n\nconst position = [51.505, -0.09]; // London coordinates\n\nfunction App() {\n  // Generate a large number of random markers for clustering demonstration\n  const markers = Array.from({ length: 500 }, (_, i) => ({\n    position: [\n      position[0] + (Math.random() - 0.5) * 0.1,\n      position[1] + (Math.random() - 0.5) * 0.2\n    ],\n    key: `marker-${i}`\n  }));\n\n  return (\n    <MapContainer center={position} zoom={10} style={{ height: '100vh', width: '100%' }}>\n      <TileLayer\n        attribution='&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors'\n        url=\"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png\"\n      />\n      <MarkerClusterGroup chunkedLoading>\n        {markers.map((marker) => (\n          <Marker key={marker.key} position={marker.position} />\n        ))}\n      </MarkerClusterGroup>\n    </MapContainer>\n  );\n}\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your `package.json` peer dependencies match:\n```json\n\"react\": \"^19.0.0\",\n\"react-dom\": \"^19.0.0\",\n\"leaflet\": \"^1.9.0\",\n\"react-leaflet\": \"^5.0.0\",\n\"@react-leaflet/core\": \"^3.0.0\"\n```","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Add these lines to your main component or entry file:\n```typescript\nimport 'react-leaflet-cluster/dist/assets/MarkerCluster.css'\nimport 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'\n```","message":"Since 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Add the following configuration to your application's entry point or map component:\n```typescript\nimport L from 'leaflet';\ndelete (L.Icon.Default as any).prototype._getIconUrl;\nL.Icon.Default.mergeOptions({\n  iconRetinaUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png',\n  iconUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png',\n  shadowUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png',\n});\n```","message":"As 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.","severity":"breaking","affected_versions":">=3.1.0"},{"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.","message":"Version 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.","severity":"gotcha","affected_versions":">=4.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading '_getIconUrl')"},{"fix":"Add the necessary CSS imports to your entry file or map component:\n`import 'react-leaflet-cluster/dist/assets/MarkerCluster.css';\nimport 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css';`","cause":"The required CSS files for MarkerClusterGroup are not imported, which is necessary since v3.0.0.","error":"MarkerClusterGroup component renders unstyled or incorrectly styled clusters (e.g., plain squares instead of styled circles)"},{"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.","cause":"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.","error":"Error: Invalid hook call. Hooks can only be called inside of the body of a function component."}],"ecosystem":"npm"}