Marker Clustering Guide

When you place a large number of markers in close proximity, they can overlap, making some markers invisible and reducing the map’s readability.

To improve visual clarity and enhance the user experience, we recommend enabling marker clustering for maps with many markers. Clustering groups nearby markers into a single, larger marker—called a cluster marker—that displays the number of individual markers it represents.

Clicking a cluster marker or zooming in will break the cluster into smaller groups or individual markers, depending on the zoom level.

Markers are clustered separately based on their category or layer. Each category displays its own cluster markers.

👉 Try it out! Zoom in and click on cluster markers to see how they expand into individual markers:

Cluster Marker Colors

By default, a cluster marker inherits the color of the category it represents.

When you use image-based markers, the cluster color is determined by one of the following:

• Automatically generated from the marker image (if a dominant color can be extracted)
• Manually set in the marker editor

If your map uses a single category or the same marker color across categories, you can style clusters by cluster size. This helps viewers quickly identify areas with higher marker density. Example:

• 1–9 markers: Yellow
• 10–49 markers: Orange
• 50+ markers: Red

Cluster Size — Suggested Styling Rules

Use simple, predictable rules to style cluster markers by the number of items they contain. Example:

• 1–9 markers: small cluster marker (≈30px)
• 10–49 markers: medium cluster marker (≈40px)
• 50+ markers: large cluster marker (≈54px)

Adjust the label size along with the marker size to improve legibility.

How to Enable Marker Clustering

1. Go to Settings > Markers
2. Toggle Enable Marker Clustering

Advanced Marker Cluster Customization

You can further customize clustering behavior using the JSON editor. Key properties include:

Maximum Zoom

Defines the maximum zoom level at which clustering occurs. Above this level, markers are shown individually. Default: 14.

Cluster Radius

Specifies the pixel radius within which markers are grouped into a cluster. A smaller radius results in more clusters and finer separation.

Cluster Size and Label Size

Adjust the cluster marker and label size with expressions.

Default:

"20, 100, 30, 500, 40"

This means:

• Fewer than 100 markers → 20px
• 100–500 markers → 30px
• 500+ markers → 40px

You can add more steps:

"20, 100, 30, 500, 40, 1000, 50"

Or set a fixed size, e.g.: 25

Cluster Colors

Set cluster colors dynamically based on the cluster size: