react-leaflet-cluster/README.md

React-leaflet-cluster is a plugin for react-leaflet. A wrapper component of Leaflet.markercluster.

# react-leaflet-cluster [![NPM version](https://badgen.net/npm/v/react-leaflet-cluster)](https://npmjs.com/package/react-leaflet-cluster) [![NPM downloads](https://badgen.net/npm/dm/react-leaflet-cluster)](https://npmjs.com/package/react-leaflet-cluster)

- [x] React 19 support
- [x] React-leaflet v5 support
- [x] Typescript support
- [x] Next.js compatibility

## Breaking Changes in v4.0.0

This release updates key peer dependencies to support React 19 and
React-Leaflet 5. Additionally, `@react-leaflet/core` is now a required peer
dependency. Make sure your project is upgraded before installing this version.

## Breaking Changes in v3.0.0

**CSS imports are now required manually** - The package no longer automatically
imports CSS files to prevent Next.js build issues. You must now import the CSS
files separately:

```tsx
import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'
import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'
```

React-leaflet-cluster is a plugin for react-leaflet. A wrapper component of
Leaflet.markercluster. Ready to be integrated into your React.js application to
create beautifully animated Marker Clustering functionality.

![QuickTime movie](https://github.com/user-attachments/assets/b4220701-8d25-4352-89b6-d878dd2f98b7)

### Examples

- [10.000 marker](https://github.com/akursat/react-leaflet-cluster/blob/main/examples/vite-example/src/components/TenThousandMarker.tsx)
- [Custom marker cluster](https://github.com/akursat/react-leaflet-cluster/blob/main/examples/vite-example/src/components/CustomMarkerCluster.tsx)

### Installation

`yarn add react-leaflet-cluster`

Or with npm:
`npm i react-leaflet-cluster`

#### Prerequisites

Make sure that you've installed react-leaflet and leaflet.

```json
"react": "19.x",
"react-dom": "19.0.0",
"leaflet": "1.9.x",
"react-leaflet": "5.0.x",
"@react-leaflet/core":
  ">=3.0.0"
```

#### CSS Import

The package requires CSS files to be imported for proper styling. Add these
imports to your main component or entry file:

```tsx
import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'
import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'
```

**Note for Next.js users**: These CSS imports are required and should be added
to your component or a global CSS file. The package no longer automatically
imports CSS to prevent Next.js build issues.

#### Icon Configuration

The package no longer automatically configures Leaflet's default marker icons.
If you need to use default markers, you'll need to configure the icon URLs
yourself. Add this configuration to your component or entry file:

```tsx
import L from 'leaflet'

// Configure default marker icons
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',
})
```

Alternatively, you can use your own custom icons for markers:

```tsx
import L from 'leaflet'

const customIcon = new L.Icon({
  iconUrl: '/path/to/your/marker-icon.png',
  iconSize: [25, 41],
  iconAnchor: [12, 41],
  popupAnchor: [1, -34],
  shadowUrl: '/path/to/your/marker-shadow.png',
  shadowSize: [41, 41],
})
```

#### Migration from v2.x

If you're upgrading from v2.x, you need to add the CSS imports manually. The
package will work without them, but the clustering won't be styled properly.

**Before (v2.x):**

```tsx
import MarkerClusterGroup from 'react-leaflet-cluster'
// CSS was automatically imported
```

**After (v3.1.0):**

```tsx
import MarkerClusterGroup from 'react-leaflet-cluster'
import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'
import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'
```

#### API

For more detailed guide and API see:
<https://akursat.gitbook.io/marker-cluster/api>

#### Usage

```tsx
import MarkerClusterGroup from 'react-leaflet-cluster'
import { MapContainer, Marker } from 'react-leaflet'
import 'leaflet/dist/leaflet.css'
// Import the required CSS for marker clustering
import 'react-leaflet-cluster/dist/assets/MarkerCluster.css'
import 'react-leaflet-cluster/dist/assets/MarkerCluster.Default.css'
import { addressPoints } from './realworld'

const Demo = () => {
  return (
    <MapContainer
      style={{ height: '500px' }}
      center={[38.9637, 35.2433]}
      zoom={6}
      scrollWheelZoom={true}
    >
      <MarkerClusterGroup chunkedLoading>
        {(addressPoints as AdressPoint).map((address, index) => (
          <Marker
            key={index}
            position={[address[0], address[1]]}
            title={address[2]}
            icon={customIcon}
          ></Marker>
        ))}
      </MarkerClusterGroup>
    </MapContainer>
  )
}
```