Skip to main content
The MarkerClusterer component groups nearby markers into clusters to improve map performance and readability when displaying many markers.

​
Import

import { MarkerClusterer } from '@react-google-maps/api'

​
Usage

import { GoogleMap, MarkerClusterer, Marker } from '@react-google-maps/api'

function MyMap() {
  const locations = [
    { lat: 37.7749, lng: -122.4194 },
    { lat: 37.7849, lng: -122.4294 },
    // ... more locations
  ]

  return (
    <GoogleMap>
      <MarkerClusterer>
        {(clusterer) => (
          <>
            {locations.map((location, i) => (
              <Marker
                key={i}
                position={location}
                clusterer={clusterer}
              />
            ))}
          </>
        )}
      </MarkerClusterer>
    </GoogleMap>
  )
}

​
Props

​
children
(markerClusterer: Clusterer) => JSX.Element
required
A render function that receives the clusterer instance and returns the markers to be clustered.
​
options
ClustererOptions
Options to configure the marker clusterer.

​
Clustering Options

​
averageCenter
boolean
Whether the center of each cluster should be the average position of all markers in the cluster.
​
gridSize
number
The grid size of a cluster in pixels. Default is 60.
​
maxZoom
number
The maximum zoom level at which clustering is enabled. When the map zoom exceeds this level, all markers are displayed individually.
​
minimumClusterSize
number
The minimum number of markers needed to form a cluster. Default is 2.
​
zoomOnClick
boolean
Whether to zoom the map when a cluster is clicked. Default is true.

​
Appearance Options

​
styles
ClusterIconStyle[]
An array of styles to apply to cluster icons. Each style defines the appearance for clusters of different sizes.
​
imagePath
string
The base path to the cluster icon images.
​
imageExtension
string
The extension for cluster icon image files. Default is ‘png’.
​
imageSizes
number[]
An array of sizes for cluster icons.
​
enableRetinaIcons
boolean
Whether to use retina-ready cluster icons.
​
clusterClass
string
The CSS class to apply to cluster icons.
​
title
string
The tooltip text to display on cluster icons.

​
Performance Options

​
batchSizeIE
number
The batch size for processing markers in Internet Explorer. Helps improve performance in IE.
​
ignoreHidden
boolean
Whether to ignore hidden markers when clustering.
​
calculator
TCalculator
A function that determines which cluster style to use based on the markers in the cluster.

​
Event Handlers

​
onClick
(cluster: Cluster) => void
Callback fired when a cluster is clicked.
​
onClusteringBegin
(markerClusterer: Clusterer) => void
Callback fired when the clustering algorithm starts.
​
onClusteringEnd
(markerClusterer: Clusterer) => void
Callback fired when the clustering algorithm finishes.
​
onMouseOver
(cluster: Cluster) => void
Callback fired when the mouse enters a cluster.
​
onMouseOut
(cluster: Cluster) => void
Callback fired when the mouse leaves a cluster.
​
onLoad
(markerClusterer: Clusterer) => void
Callback fired when the marker clusterer instance is loaded.
​
onUnmount
(markerClusterer: Clusterer) => void
Callback fired when the marker clusterer is unmounted.

​
Types

​
ClusterIconStyle

Defines the visual style of a cluster icon. 
interface ClusterIconStyle {
  url: string          // URL of the cluster icon image
  height: number       // Height of the icon in pixels
  width: number        // Width of the icon in pixels
  textColor?: string   // Color of the text showing marker count
  textSize?: number    // Size of the text in pixels
  anchorText?: [number, number]  // Text anchor position
  anchorIcon?: [number, number]  // Icon anchor position
}

​
TCalculator

A function that calculates which cluster style to use. 
type TCalculator = (
  markers: google.maps.Marker[],
  numStyles: number
) => {
  text: string   // Text to display on the cluster
  index: number  // Index of the style to use
}

​
Example with Custom Styles

const clusterStyles = [
  {
    url: '/cluster-icon-1.png',
    height: 50,
    width: 50,
    textColor: '#ffffff',
    textSize: 12,
  },
  {
    url: '/cluster-icon-2.png',
    height: 60,
    width: 60,
    textColor: '#ffffff',
    textSize: 14,
  },
]

<MarkerClusterer
  options={{
    gridSize: 50,
    maxZoom: 15,
    minimumClusterSize: 3,
  }}
  styles={clusterStyles}
  onClick={(cluster) => {
    console.log('Cluster clicked:', cluster)
  }}
>
  {(clusterer) => (
    // ... your markers
  )}
</MarkerClusterer>

​
Notes

  • The MarkerClusterer component uses the @react-google-maps/marker-clusterer package internally.
  • Markers must be passed the clusterer prop to be included in clustering.
  • Custom cluster icons should be optimized for web use to ensure good performance.
  • The clustering algorithm runs automatically when markers are added, removed, or when the map viewport changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us