{"id":11741,"library":"react-leaflet-markercluster","title":"React Leaflet Markercluster","description":"react-leaflet-markercluster is a dedicated React component that provides an intuitive wrapper for the popular Leaflet.markercluster plugin, designed specifically for use within react-leaflet applications. It addresses the common challenge of visualizing a large number of markers on a map by dynamically grouping them into clusters at various zoom levels, preventing clutter and improving map performance and user experience. The current stable release is v4.2.1, with v5.0.0-rc.0 currently in a release candidate phase to support React 19 and react-leaflet v5. The package aims for stability and compatibility with major react-leaflet versions, often releasing new major versions to align with its peer dependencies. Its primary differentiator is its seamless integration into the react-leaflet ecosystem, allowing developers to simply wrap existing Leaflet Marker components within a `<MarkerClusterGroup />` to enable clustering functionality without complex imperative Leaflet API calls, while also exposing full control over Leaflet.markercluster options via component props.","status":"active","version":"5.0.0-rc.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/YUzhva/react-leaflet-markercluster","tags":["javascript","react","leaflet","react-leaflet","markercluster","marker","cluster","typescript"],"install":[{"cmd":"npm install react-leaflet-markercluster","lang":"bash","label":"npm"},{"cmd":"yarn add react-leaflet-markercluster","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-leaflet-markercluster","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core mapping library, peer dependency.","package":"leaflet","optional":false},{"reason":"The underlying marker clustering plugin, peer dependency.","package":"leaflet.markercluster","optional":false},{"reason":"React wrapper for Leaflet, peer dependency.","package":"react-leaflet","optional":false},{"reason":"React library, peer dependency.","package":"react","optional":false}],"imports":[{"note":"The MarkerClusterGroup component is exported as a default. While CommonJS `require` might function in some setups, modern React applications should prefer ESM `import` as the package supports ESM since v4.1.2.","wrong":"import { MarkerClusterGroup } from 'react-leaflet-markercluster';\nconst MarkerClusterGroup = require('react-leaflet-markercluster');","symbol":"MarkerClusterGroup","correct":"import MarkerClusterGroup from 'react-leaflet-markercluster';"},{"note":"These styles are essential for the visual rendering and functionality of clustered markers. Ensure `leaflet/dist/leaflet.css` is imported before this for proper cascading.","wrong":"import 'react-leaflet-markercluster/dist/styles.css';","symbol":"Styles","correct":"import 'react-leaflet-markercluster/styles';"},{"note":"This type import is useful for explicitly typing the props of the MarkerClusterGroup component in TypeScript projects. Types are bundled with the package since v4.2.0.","wrong":"import { MarkerClusterGroupProps } from 'react-leaflet-markercluster';","symbol":"MarkerClusterGroupProps (Type)","correct":"import type { MarkerClusterGroupProps } from 'react-leaflet-markercluster';"}],"quickstart":{"code":"import React from 'react';\nimport { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';\nimport MarkerClusterGroup from 'react-leaflet-markercluster';\n\n// Ensure Leaflet and MarkerClusterGroup styles are loaded\nimport 'leaflet/dist/leaflet.css';\nimport 'react-leaflet-markercluster/styles';\n\nfunction MyMapComponent() {\n  const markers = [\n    { position: [49.8397, 24.0297], id: 1, name: 'Lviv' },\n    { position: [52.2297, 21.0122], id: 2, name: 'Warsaw' },\n    { position: [51.5074, -0.0901], id: 3, name: 'London' },\n    { position: [50.0880, 14.4208], id: 4, name: 'Prague' },\n    { position: [48.8566, 2.3522], id: 5, name: 'Paris' },\n    { position: [40.7128, -74.0060], id: 6, name: 'New York' },\n    { position: [34.0522, -118.2437], id: 7, name: 'Los Angeles' },\n    { position: [35.6895, 139.6917], id: 8, name: 'Tokyo' }\n  ];\n\n  return (\n    <MapContainer\n      className=\"markercluster-map\"\n      center={[51.0, 19.0]}\n      zoom={4}\n      maxZoom={18}\n      style={{ height: '90vh', width: '100%' }} // Inline style for quick demo\n    >\n      <TileLayer\n        url=\"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png\"\n        attribution='&copy; <a href=\"http://osm.org/copyright\">OpenStreetMap</a> contributors'\n      />\n\n      <MarkerClusterGroup chunkedLoading>\n        {markers.map((marker) => (\n          <Marker key={marker.id} position={marker.position}>\n            <Popup>{marker.name}</Popup>\n          </Marker>\n        ))}\n      </MarkerClusterGroup>\n    </MapContainer>\n  );\n}\n\nexport default MyMapComponent;","lang":"typescript","description":"This quickstart demonstrates how to set up a basic Leaflet map with `react-leaflet` and enable marker clustering using `react-leaflet-markercluster`, showing multiple markers that group dynamically on zoom."},"warnings":[{"fix":"Upgrade peer dependencies (React, react-leaflet, leaflet, leaflet.markercluster) to their latest compatible versions as specified by react-leaflet-markercluster's package.json.","message":"Major version 5.x introduces breaking changes for compatibility with React 19 and react-leaflet 5. This requires upgrading your entire React-Leaflet ecosystem.","severity":"breaking","affected_versions":">=5.0.0-rc.0"},{"fix":"Refactor marker objects to use the 'position' key, e.g., `{ position: [lat, lng] }` instead of `{ lat, lng }`.","message":"The MarkerClusterGroup component removed direct support for 'marker' object 'lat' and 'lng' keys. Marker positions must now be provided via the 'position' key.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Pass all Leaflet.markercluster options directly as props to the `<MarkerClusterGroup />` component instead of nesting them under an `options` prop.","message":"The 'options' property on MarkerClusterGroup was removed. All Leaflet.markercluster options should be passed directly as props to the component.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `leaflet/dist/leaflet.css` and `react-leaflet-markercluster/styles` are imported at the root of your application, typically in a CSS file or directly in a JS entry point before your components render.","message":"Stylesheets for both Leaflet and react-leaflet-markercluster must be correctly imported for the map and clustering to render properly and visibly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install `leaflet.markercluster` using npm or yarn: `npm install leaflet.markercluster` or `yarn add leaflet.markercluster`.","message":"The package relies on `leaflet.markercluster` as a peer dependency, which must be installed alongside `react-leaflet-markercluster`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `leaflet` and `leaflet.markercluster` peer dependencies are installed and properly imported/configured in your project before rendering React components that depend on them.","cause":"Leaflet or Leaflet.markercluster is not correctly initialized or available globally (e.g., L is not defined) before react-leaflet-markercluster attempts to use it.","error":"TypeError: Cannot read properties of undefined (reading 'addLayer')"},{"fix":"Verify your import statement to be `import MarkerClusterGroup from 'react-leaflet-markercluster';`.","cause":"Incorrect import of `MarkerClusterGroup`, commonly by attempting to use a named import (`{ MarkerClusterGroup }`) instead of a default import, or using CJS `require` in a modern ESM context.","error":"MarkerClusterGroup is not a function or a valid JSX element."},{"fix":"Add `import 'leaflet/dist/leaflet.css';` and `import 'react-leaflet-markercluster/styles';` to your application's entry point (e.g., `App.tsx` or `index.ts`) or include them via HTML `<link>` tags.","cause":"Required CSS stylesheets for Leaflet and/or react-leaflet-markercluster are not loaded into the browser.","error":"Map is not visible or marker clusters are not styled correctly (e.g., default blue Leaflet markers instead of clusters)."}],"ecosystem":"npm"}