Understanding MarkerClusterer

Oct 13, 2025 by talynt.org 136 views

Introduction

When working with Google Maps and the vis.gl/react-google-maps library, MarkerClusterer is a powerful tool for managing large numbers of markers on a map. However, sometimes, despite following the official documentation and examples, MarkerClusterer may not render correctly, displaying individual markers instead of clusters. In this article, we will explore the common issues and provide a step-by-step solution to get MarkerClusterer working as expected.

Understanding MarkerClusterer

MarkerClusterer is a feature of the Google Maps API that allows you to group multiple markers together on a map, making it easier to manage large numbers of markers. When a cluster is created, it displays a single marker with a count of the number of markers within the cluster. When a user clicks on the cluster, the individual markers within the cluster are displayed.

Common Issues with MarkerClusterer

Before we dive into the solution, let's identify some common issues that may be causing MarkerClusterer to not render correctly:

Incorrect library versions: Make sure you are using the latest versions of vis.gl/react-google-maps and Google Maps API.
Missing or incorrect configuration: Double-check that you have properly configured MarkerClusterer in your code.
Insufficient data: Ensure that you have enough data to create clusters.

Step-by-Step Solution

To get MarkerClusterer working correctly, follow these steps:

Step 1: Install Required Libraries

First, make sure you have installed the required libraries:

npm install @react-google-maps/api
npm install vis-gl

Step 2: Import Required Components

Import the required components from vis.gl/react-google-maps:

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

Step 3: Configure MarkerClusterer

Configure MarkerClusterer by passing the required props:

const options = {
  gridSize: 60,
  minimumClusterSize: 2,
};
const clusterer = new MarkerClusterer(map, markers, options);

Step 4: Create Markers

Create markers and add them to the map:

const markers = [
  {
    position: { lat: 37.7749, lng: -122.4194 },
    key: 'marker-1',
  },
  {
    position: { lat: 37.7859, lng: -122.4364 },
    key: 'marker-2',
  },
  // Add more markers here...
];
const map = new google.maps.Map(document.getElementById('map'), 
center { lat: 37.7749, lng: -122.4194 ,
zoom: 12,
});

Step 5: Render MarkerClusterer

Render MarkerClusterer on the map:

<GoogleMap
  mapContainerStyle={{ height: '100vh', width: '100vw' }}
  center={{ lat: 37.7749, lng: -122.4194 }}
  zoom={12}
>
  <MarkerClusterer
    averageCenter
    enableRetinaIcons
    gridSize={60}
    minimumClusterSize={2}
  >
    {({ children }) => children}
  </MarkerClusterer>
</GoogleMap>

Example Use Case

Here's an example use case for MarkerClusterer:

Suppose you have a list of locations with latitude and longitude coordinates. You want to display these locations on a map, but you have a large number of locations, and you want to group them together using MarkerClusterer.

import React, { useState, useEffect } from 'react';
import { GoogleMap, MarkerClusterer } from '@react-google-maps/api';
const locations = [
 lat 37.7749, lng: -122.4194 ,
 lat 37.7859, lng: -122.4364 ,
 lat 37.7969, lng: -122.4574 ,
// Add more locations here...
];
const App = () => {
const [markers, setMarkers] = useState([]);
useEffect(() => 
const createMarkers = () => {
const markers = locations.map((location, index) => ({
position location,
key: `marker-${index`,
}));
setMarkers(markers);
};
createMarkers();
}, []);
return (
<GoogleMap
mapContainerStyle={ height '100vh', width: '100vw' }
center={ lat 37.7749, lng: -122.4194 }
zoom={12}
>
<MarkerClusterer
averageCenter
enableRetinaIcons
gridSize={60}
minimumClusterSize={2}
>
{({ children }) => children}
</MarkerClusterer>
</GoogleMap>
);
};
export default App;

Conclusion

Introduction

MarkerClusterer is a powerful tool for managing large numbers of markers on a map. However, despite its popularity, many developers still have questions about how to use it effectively. In this article, we will answer some of the most frequently asked questions about MarkerClusterer.

Q: What is MarkerClusterer?

A: MarkerClusterer is a feature of the Google Maps API that allows you to group multiple markers together on a map, making it easier to manage large numbers of markers.

Q: How do I install MarkerClusterer?

A: To install MarkerClusterer, you need to install the vis.gl/react-google-maps library and import the MarkerClusterer component.

npm install @react-google-maps/api

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

Q: How do I configure MarkerClusterer?

A: To configure MarkerClusterer, you need to pass the required props to the MarkerClusterer component. The most common props are:

gridSize: The size of the grid that the markers are clustered into.
minimumClusterSize: The minimum number of markers that must be in a cluster before it is displayed.

const options = {
  gridSize: 60,
  minimumClusterSize: 2,
};
const clusterer = new MarkerClusterer(map, markers, options);

Q: How do I create markers for MarkerClusterer?

A: To create markers for MarkerClusterer, you need to create an array of marker objects. Each marker object should have the following properties:

position: The latitude and longitude of the marker.
key: A unique key for the marker.

const markers = [
  {
    position: { lat: 37.7749, lng: -122.4194 },
    key: 'marker-1',
  },
  {
    position: { lat: 37.7859, lng: -122.4364 },
    key: 'marker-2',
  },
  // Add more markers here...
];

Q: How do I render MarkerClusterer on the map?

A: To render MarkerClusterer on the map, you need to wrap the MarkerClusterer component with the GoogleMap component.

<GoogleMap
  mapContainerStyle={{ height: '100vh', width: '100vw' }}
  center={{ lat: 37.7749, lng: -122.4194 }}
  zoom={12}
>
  <MarkerClusterer
    averageCenter
    enableRetinaIcons
    gridSize={60}
    minimumClusterSize={2}
  >
    {({ children }) => children}
  </MarkerClusterer>
</GoogleMap>

Q: How do I handle marker clicks?

A: To handle marker clicks, you need to pass a function to the onMarkerClick prop of the MarkerClusterer component.

<MarkerClusterer
  averageCenter
  enableRetinaIcons
  gridSize={60}
  minimumClusterSize={2}
  onMarkerClick={(marker) => console.log(marker)}
>
  {({ children }) => children}
</MarkerClusterer>

Q: How do I handle cluster clicks?

A: To handle cluster clicks, you need to pass a function to the onClusterClick prop of the MarkerClusterer component.

<MarkerClusterer
  averageCenter
  enableRetinaIcons
  gridSize={60}
  minimumClusterSize={2}
  onClusterClick={(cluster) => console.log(cluster)}
>
  {({ children }) => children}
</MarkerClusterer>

Q: How do I customize the appearance of MarkerClusterer?

A: To customize the appearance of MarkerClusterer, you can pass custom styles to the MarkerClusterer component.

<MarkerClusterer
  averageCenter
  enableRetinaIcons
  gridSize={60}
  minimumClusterSize={2}
  styles={{
    marker: {
      url: 'https://example.com/marker.png',
    },
    cluster: {
      url: 'https://example.com/cluster.png',
    },
  }}
>
  {({ children }) => children}
</MarkerClusterer>

Conclusion

In this article, we answered some of the most frequently asked questions about MarkerClusterer. We covered topics such as installation, configuration, marker creation, rendering, handling clicks, and customizing appearance. By following these answers, you should be able to use MarkerClusterer effectively in your applications.