React Leaflet Markercluster

Common errors

• TypeError: Cannot read properties of undefined (reading 'addLayer')

  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.
  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.

• MarkerClusterGroup is not a function or a valid JSX element.

  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.
  fix Verify your import statement to be `import MarkerClusterGroup from 'react-leaflet-markercluster';`.

• Map is not visible or marker clusters are not styled correctly (e.g., default blue Leaflet markers instead of clusters).

  cause Required CSS stylesheets for Leaflet and/or react-leaflet-markercluster are not loaded into the browser.
  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.

Warnings

• breaking Major version 5.x introduces breaking changes for compatibility with React 19 and react-leaflet 5. This requires upgrading your entire React-Leaflet ecosystem.
  Fix: Upgrade peer dependencies (React, react-leaflet, leaflet, leaflet.markercluster) to their latest compatible versions as specified by react-leaflet-markercluster's package.json.
• breaking The MarkerClusterGroup component removed direct support for 'marker' object 'lat' and 'lng' keys. Marker positions must now be provided via the 'position' key.
  Fix: Refactor marker objects to use the 'position' key, e.g., `{ position: [lat, lng] }` instead of `{ lat, lng }`.
• breaking The 'options' property on MarkerClusterGroup was removed. All Leaflet.markercluster options should be passed directly as props to the component.
  Fix: Pass all Leaflet.markercluster options directly as props to the `<MarkerClusterGroup />` component instead of nesting them under an `options` prop.
• gotcha Stylesheets for both Leaflet and react-leaflet-markercluster must be correctly imported for the map and clustering to render properly and visibly.
  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.
• gotcha The package relies on `leaflet.markercluster` as a peer dependency, which must be installed alongside `react-leaflet-markercluster`.
  Fix: Install `leaflet.markercluster` using npm or yarn: `npm install leaflet.markercluster` or `yarn add leaflet.markercluster`.

Install

• npm install react-leaflet-markercluster npm
• yarn add react-leaflet-markercluster yarn
• pnpm add react-leaflet-markercluster pnpm

Imports

• MarkerClusterGroup
  wrong:

  import { MarkerClusterGroup } from 'react-leaflet-markercluster';
  const MarkerClusterGroup = require('react-leaflet-markercluster');

  correct:

  import MarkerClusterGroup from 'react-leaflet-markercluster';

  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.
• Styles
  wrong:

  import 'react-leaflet-markercluster/dist/styles.css';

  correct:

  import 'react-leaflet-markercluster/styles';

  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.
• MarkerClusterGroupProps (Type)
  wrong:

  import { MarkerClusterGroupProps } from 'react-leaflet-markercluster';

  correct:

  import type { MarkerClusterGroupProps } from 'react-leaflet-markercluster';

  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.

Quickstart

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.

import React from 'react';
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
import MarkerClusterGroup from 'react-leaflet-markercluster';

// Ensure Leaflet and MarkerClusterGroup styles are loaded
import 'leaflet/dist/leaflet.css';
import 'react-leaflet-markercluster/styles';

function MyMapComponent() {
  const markers = [
    { position: [49.8397, 24.0297], id: 1, name: 'Lviv' },
    { position: [52.2297, 21.0122], id: 2, name: 'Warsaw' },
    { position: [51.5074, -0.0901], id: 3, name: 'London' },
    { position: [50.0880, 14.4208], id: 4, name: 'Prague' },
    { position: [48.8566, 2.3522], id: 5, name: 'Paris' },
    { position: [40.7128, -74.0060], id: 6, name: 'New York' },
    { position: [34.0522, -118.2437], id: 7, name: 'Los Angeles' },
    { position: [35.6895, 139.6917], id: 8, name: 'Tokyo' }
  ];

  return (
    <MapContainer
      className="markercluster-map"
      center={[51.0, 19.0]}
      zoom={4}
      maxZoom={18}
      style={{ height: '90vh', width: '100%' }} // Inline style for quick demo
    >
      <TileLayer
        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
        attribution='&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
      />

      <MarkerClusterGroup chunkedLoading>
        {markers.map((marker) => (
          <Marker key={marker.id} position={marker.position}>
            <Popup>{marker.name}</Popup>
          </Marker>
        ))}
      </MarkerClusterGroup>
    </MapContainer>
  );
}

export default MyMapComponent;