MarkerCluster

The MarkerCluster object displays a group of markers under a single "cluster" marker.

MarkerCluster extends Base.

The clustering functionality uses the Google Maps MarkerClusterer library.

Example usage

const cluster = G.markerCluster(map);
const marker = G.marker({
    position: G.latLng(0, 0),
});
marker.show(map);
cluster.addMarker(marker);

Creating the MarkerCluster object

G.markerCluster(
    map: Map,
    markers?: Marker[] | MarkerClusterOptions,
    options?: MarkerClusterOptions
): MarkerCluster

There are a few ways that you can set up the MarkerCluster object.

Only pass the Map object

G.markerCluster(map: Map): MarkerCluster

Parameter	Type	Required	Description
map	Map	Yes	The map that the cluster will display on.

const cluster = G.markerCluster(map);

Pass the Map object and markers

You can add the markers in the cluster at the same time that you create the cluster object. You can also add additional markers with the addMarker or addMarkers methods.

G.markerCluster(map: Map, markers: Marker[]): MarkerCluster

Parameter	Type	Required	Description
map	Map	Yes	The map that the cluster will display on.
markers	Marker[]	Yes	The array of markers to add to the cluster.

const markers = [];
markers.push(G.marker({
    latitude: 48.2,
    longitude: 2.3,
    map: map,
}));
markers.push(G.marker({
    latitude: 48.3,
    longitude: 2.2,
    map: map,
}));
const cluster = G.markerCluster(map, markers);

Pass the Map object, markers, and cluster options

G.markerCluster(map: Map, markers: Marker[], options: MarkerClusterOptions): MarkerCluster

Parameter	Type	Required	Description
map	Map	Yes	The map that the cluster will display on.
markers	Marker[]	Yes	The array of markers to add to the cluster.
options	MarkerClusterOptions	Yes	The options for the cluster.

const markers = [];
markers.push(G.marker({
    latitude: 48.2,
    longitude: 2.3,
    map: map,
}));
markers.push(G.marker({
    latitude: 48.3,
    longitude: 2.2,
    map: map,
}));
const clusterOptions = {
    defaultRenderOptions: {
        colorRangeTop: '#d62828',
        colorRangeBottom: {
            bgColor: '#E5E5E5',
            textColor: '#000000',
        },
        centerOpacity: 0.7,
        middleOpacity: 0.4,
        outerOpacity: 0.2,
        labelFontFamily: 'roboto,arial,sans-serif',
        labelFontSize: '12px',
    },
}
const cluster = G.markerCluster(map, markers, clusterOptions);

Pass the Map object and cluster options

G.markerCluster(map: Map, options: MarkerClusterOptions): MarkerCluster

If you aren't passing an array of markers then you can pass the cluster options as the second parameter in place of the markers.

Parameter	Type	Required	Description
map	Map	Yes	The map that the cluster will display on.
options	MarkerClusterOptions	Yes	The options for the cluster.

const clusterOptions = {
    defaultRenderOptions: {
        colorRangeTop: '#d62828',
        colorRangeBottom: {
            bgColor: '#E5E5E5',
            textColor: '#000000',
        },
        centerOpacity: 0.7,
        middleOpacity: 0.4,
        outerOpacity: 0.2,
        labelFontFamily: 'roboto,arial,sans-serif',
        labelFontSize: '12px',
    },
}
const cluster = G.markerCluster(map, clusterOptions);

You could also pass an empty array or null as the second parameter.

const cluster = G.markerCluster(map, [], clusterOptions);

// or

const cluster = G.markerCluster(map, null, clusterOptions);

MarkerCluster options

Option	Type	Default	Description
algorithm	string	'supercluster'	A simple string to set the cluster algorithm. Accepted values are `grid`, `supercluster`, and `noop`. If `noop` is set then no clustering happens. This is an alternate way to set the algorithm if you don't want to use the algorithmClass. You can still set algorithmOptions if you use this method.
algorithmClass	Algorithm		The algorithm to cluster markers. This determines how many markers are clustered together.
algorithmOptions	object		The options for the algorithm. See AlgorithmOptions, GridOptions, and SuperCluster for more information.
defaultRenderOptions	DefaultRenderOptions		The options for the default renderer.
imageRendererOptions	ImageRendererOptions		The options for the image renderer. If this is set then the image renderer will be used instead of the default renderer.
onClusterClick	onClusterClickHandler		A callback function to handle when the marker is clicked.
maxZoom	number	13	The maxium zoom level to cluster markers. Higher numbers means more zoomed in. This is used by the SuperClusterAlgorithm and the GridAlgorithm. If set, this will override the maxZoom option in the `algorithmOptions`.
minPoints	number	3	Minimum number of points to form a cluster. If set, this will override the `minPoints` option in the `algorithmOptions`.
radius	number	40	The radius to use to determine which markers to cluster. The larger the number the more markers to include in a cluster and fewer clusters. The lower the number the more clusters there may be. This is used by the SuperClusterAlgorithm. If set, this will override the `radius` option in the `algorithmOptions`.
renderer	Renderer	DefaultRenderer	An object that converts a cluster into a Marker.

MarkerCluster click handler

onClusterClickHandler = (event: google.maps.MapMouseEvent, cluster: Cluster, map: google.maps.Map) => void

You can set up custom click handler for when the cluster marker is clicked. By default the map will zoom in to view the markers in the cluster.

Marker cluster rendering

There are two types of renderers for the marker clusters.

Default renderer - Display a circle marker with different colors depending on how many markers are in the cluster.
Image renderer - Display images for the cluster markers. A different image can be used depending on how many markers are in the cluster.

The renderer uses the specified algorithm in the MarkerCluster options to determine how many markers to show in the cluster.

Default renderer

The default renderer displays a marker in the shape of a circle with an outer ring that has some opacity. The number of markers in the cluster shows in the middle of the cluster marker.

Example usage.

const cluster = G.markerCluster(map, {
    defaultRendererOptions: {
        colors: {
            0: '#0000ff',
            10: '#00ff00',
            20: {
                bgColor: '#ff00ff',
                textColor: '#000000',
            },
        },
        centerOpacity: 0.7,
        middleOpacity: 0.4,
        outerOpacity: 0.2,
        labelFontFamily: 'roboto,arial,sans-serif',
        labelFontSize: '12px',
        showNumber: true,
    }
});
const marker = G.marker({
    position: G.latLng(0, 0),
});
marker.show(map);
cluster.addMarker(marker);

Cluster colors object

Type ClusterColor.

When specifying colors to the cluster markers, you can either pass a color string value, or pass an object that contains the background color and the text color.

Option	Type	Description
bgColor	string	The background color for the marker.
textColor	string	The text color for the marker.

Type ClusterColors.

This represensts an object of colors.

ClusterColors: {
    [key: number]: string | ClusterColor;
}

The key value is the marker count to match the color to. If the marker count is greater or equal to the key value and this is the greatest match, then this color will be used.

The first color should have a key of 0 or 1 to handle clusters with 1 or more markers.

The value can either be a color string or a ClusterColor.

Setting the marker colors

There are two ways to set the colors of the markers.

Use defaultRendererOptions.colorRangeBottom and defaultRendererOptions.colorRangeTop to set the two colors that could be used.

If the cluster count is greater than the average number of markers in all clusters, then the defaultRendererOptions.colorRangeTop color is used. Otherwise the defaultRendererOptions.colorRangeBottom color is used.

G.markerCluster(map, {
    defaultRendererOptions: {
        colorRangeBottom: '#d62828',
        colorRangeTop: {
            bgColor: '#ff00ff',
            textColor: '#000000',
        }
    }
});

Specify the colors to use with the defaultRendererOptions.colors object.

The object key is the marker count to match and the value is the color to use. If the number of markers in the cluster is greater or equal to the marker count then that color is used.

G.markerCluster(map, {
    defaultRendererOptions: {
        colors: {
            0: '#75A15D',
            10: '#D97E31',
            20: {
                bgColor: '#E5E5E5',
                textColor: '#000000',
            },
        }
    }
});

Default renderer options

Type DefaultRenderOptions.

These are the options for the default renderer.

Option	Type	Default	Description
colorRangeBottom	string	'#ff0000'	The color to use for the cluster if it has less than or equal to than the average number of markers in all cluster.
colorRangeTop	string	'#0000ff'	The color to use for the cluster if it has more than the average number of markers in all cluster.
colors	ClusterColors		An object that holds the colors for the clusters.
labelFontFamily	string	'roboto,arial,sans-serif'	The font family for the cluster marker label.
labelFontSize	number or string	'12px'	The font size of the label text (equivalent to the CSS font-size property). If it's set to a number then "px" will be added to the end of the number.
centerOpacity	number	0.7	The opacity to use for the center of the marker.
middleOpacity	number	0.4	The opacity to use for the outer ring of the marker.
outerOpacity	number	0.2	The opacity to use for the outer ring of the marker.
showNumber	boolean	true	Whether to show the number of markers in the cluster.

Image renderer

The image renderer displays an image for the cluster marker. The number of markers in the cluster shows in the middle of the cluster marker.

Example usage.

const cluster = G.markerCluster('map', {
    imageRendererOptions: {
        images: {
            5: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m1.png',
            10: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m2.png',
            15: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m3.png',
            20: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m4.png',
            30: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m5.png',
        }
    }
});
const marker = G.marker({
    position: G.latLng(0, 0),
});
marker.show(map);
cluster.addMarker(marker);

Cluster image object type

Type ClusterImage.

The cluster image can be a string containing the URL for the image file, or it can be an object of image data. The ClusterImage type represents the image object.

These values are used to set up the Icon object for the Marker and the marker label.

Option	Type	Default	Description
height	number		The height of the image. Use this or `size`.
labelClassName	string		A CSS class name to be added to the label element.
labelColor	string	'black'	The color of the label text.
labelFontFamily	string		The font family of the label text (equivalent to the CSS font-family property).
labelFontSize	number or string	'12px'	The font size of the label text (equivalent to the CSS font-size property). If it's set to a number then "px" will be added to the end of the number.
labelFontWeight	string		The font weight of the label text (equivalent to the CSS font-weight property).
scaledHeight	number		The height of the image after scaling, if any. Use this property to stretch/shrink an image or a sprite. Use this or `scaledSize`.
scaledSize	SizeValue		The display size of the sprite or image. When using sprites, you must specify the sprite size. If the size is not provided, it will be set when the image loads.
scaledWidth	number		The width of the image after scaling, if any. Use this property to stretch/shrink an image or a sprite. Use this or `scaledSize`.
size	SizeValue		The display size of the sprite or image. When using sprites, you must specify the sprite size. If the size is not provided, it will be set when the image loads.
url	string		The url of the image to use for the cluster.
width	number		The width of the image. Use this or `size`.

Cluster images type

Type ClusterImages.

ClusterImages = {
    // The image to use for the cluster
    [key: number]: string | ClusterImage;
}

The key value is the marker count to match the color to. If the marker count is greater or equal to the key value and this is the greatest match, then this color will be used.

The first image should have a key of 0 or 1 to handle clusters with 1 or more markers.

The value should be an object containing the image URL, the width, and height of the image.

{
    0: {
        url: 'https://mysite.com/markerSm.svg',
        labelColor: '#fff',
        labelFontSize: '15px',
        labelFontWeight: 'bold',
    },
    10: {
        url: 'https://mysite.com/markerMd.svg',
        labelColor: '#fff',
        labelFontSize: 10,
        labelFontFamily: 'Times New Roman',
        labelClassName: 'my-custom-class-for-label',
    },
    20: 'https://mysite.com/markerLg.svg',
}

Image renderer options

Type ImageRendererOptions.

These are the options for the image renderer.

Option	Type	Default	Description
images	ClusterImages		An object that holds the images for the clusters.
image	ClusterImage		A single image for the cluster. Use this instead of "images" if you only need one image for the cluster.
labelClassName	string		A CSS class name to be added to the label element.
labelColor	string	'black'	The color of the label text.
labelFontFamily	string		The font family of the label text (equivalent to the CSS font-family property).
labelFontSize	number or string	'12px'	The font size of the label text (equivalent to the CSS font-size property). If it's set to a number then "px" will be added to the end of the number.
labelFontWeight	string		The font weight of the label text (equivalent to the CSS font-weight property).
showNumber	boolean	true	Whether to show the number of markers in the cluster.

Styling the label text

While you can set a class name with labelClassName for the label text, you can only style the label color, font family, font size, and font weight by passing those values in the cluster configuration.

This marker cluster object creates a Marker object for each cluster marker, which ultimately uses the Google Maps Javascript API to create the marker. Google Maps only lets you set the color, font family, font size, and font weight by passing those as properties to the marker object.

Even if you don't configure a value for the color, font family, font size, or font weight, the Google Maps library will output inline styles on the label div tag that it outputs. Below is an example of the default style values.

<div aria-hidden="true" style="color: rgb(0, 0, 0); font-size: 14px; font-family: Roboto, Arial, sans-serif;">3</div>

Because the styles are inline and there is no way to not have them output, it's advisable to not use a custom CSS class to style those values. (Technically you can use !important with your custom CSS, but that's not best-practice.)

Below is an example of setting up the default renderer with some font styles.

const clusterOptions = {
    defaultRenderOptions: {
        colorRangeTop: '#d62828',
        colorRangeBottom: {
            bgColor: '#E5E5E5',
            textColor: '#000000',
        },
        centerOpacity: 0.7,
        middleOpacity: 0.4,
        outerOpacity: 0.2,
        labelFontFamily: 'Georgia, serif',
        labelFontSize: '12px',
        labelFontWeight: '700'
    },
}

Below is an example of setting up an image renderer with some font styles

const clusterOptions = {
    0: {
        url: 'https://mysite.com/markerSm.svg',
        labelColor: '#fff',
        labelFontSize: '15px',
        labelFontWeight: 'bold',
    },
    10: {
        url: 'https://mysite.com/markerMd.svg',
        labelColor: '#fff',
        labelFontSize: 10,
        labelFontFamily: 'Times New Roman',
        labelClassName: 'my-custom-class-for-label',
    },
    20: 'https://mysite.com/markerLg.svg',
}

Methods

Methods inherited from Base.

addMarker

addMarker(marker: Marker, draw: boolean = true): MarkerCluster

Add a marker to the cluster.

Parameter	Type	Required	Description
marker	Marker	Yes	The marker to add to the cluster.
draw	boolean		Whether to redraw the clusters after adding the marker. Defaults to `true`.

cluster = G.markerCluster('map');
const marker = G.marker({
    position: G.latLng(0, 0),
    map: map
});
cluster.addMarker(marker);

addMarkers

addMarkers(markers: Marker[], draw: boolean = true): MarkerCluster

Added one or more markers to the cluster.

Parameter	Type	Required	Description
markers	Marker[]	Yes	The markers to add to the cluster.
draw	boolean		Whether to redraw the clusters after adding the markers. Defaults to `true`.

cluster = G.markerCluster('map');
const markers = [
    G.marker({
        position: G.latLng(0, 0),
        map: map
    }),
    G.marker({
        position: G.latLng(1, 2),
        map: map
    })
];
cluster.addMarkers(markers);

clearMarkers

clearMarkers(draw: boolean = true): MarkerCluster

Clears all the markers in the marker cluster. This does not remove the markers from the map.

Parameter	Type	Required	Description
draw	boolean		Whether to redraw the clusters after removing the markers. Defaults to `true`.

removeMarker

removeMarker(marker: Marker, draw: boolean = false): MarkerCluster

Removes a single marker from the cluster.

Parameter	Type	Required	Description
marker	Marker	Yes	The marker to remove from the cluster.
draw	boolean		Whether to redraw the clusters after removing the marker. Defaults to `true`.

cluster.removeMarker(marker);

render

render(): MarkerCluster

Force a recalculation and redraw of all the marker clusters.

You will almost never need to call this.

cluster.render();

Example usage​

Creating the MarkerCluster object​

Only pass the Map object​

Pass the Map object and markers​

Pass the Map object, markers, and cluster options​

Pass the Map object and cluster options​

MarkerCluster options​

MarkerCluster click handler​

Marker cluster rendering​

Default renderer​

Cluster colors object​

Setting the marker colors​

Default renderer options​

Image renderer​

Cluster image object type​

Cluster images type​

Image renderer options​

Styling the label text​

Methods​

addMarker​

addMarkers​

clearMarkers​

removeMarker​

render​