MapConductorDocs / Extensions / Marker clustering
Markers at scale
Nearby markers are grouped into clusters automatically and expand again as you zoom in — the same code inside any provider map view.
ANDROID
com.mapconductor:marker-clustering
iOS
MapConductorMarkerCluster
REACT
@mapconductor/react-marker-clustering
01 · Install
app/build.gradle.kts
implementation("com.mapconductor:marker-clustering")Package.swift
.package(url: "https://github.com/MapConductor/ios-marker-cluster", from: "1.1.4"), .product(name: "MapConductorMarkerCluster", package: "ios-marker-cluster"),
terminal
npm install @mapconductor/react-marker-clustering
02 · Usage
Pass your array of marker states to the cluster group. The marker states themselves are the ordinary ones; nothing else changes.
ClusteredMap.kt · Jetpack Compose
val markerStates: List<MarkerState> = remember { buildMarkerList() }
val clusterState = remember {
MarkerClusterGroupState(
clusterRadiusPx = 90.0,
minClusterSize = 5,
onClusterClick = { cluster -> /* handle tap */ },
)
}
MapLibreMapView(state = mapState) {
MarkerClusterGroup(state = clusterState, markers = markerStates)
}ClusteredMap.swift · SwiftUI
@State private var clusterState = MarkerClusterGroupState(
clusterRadiusPx: 90,
minClusterSize: 5,
onClusterClick: { cluster in /* handle tap */ }
)
MapLibreMapView(state: mapState) {
MarkerClusterGroup(state: clusterState, markers: markerStates)
}ClusteredMap.tsx · React
import { MarkerClusterGroup } from '@mapconductor/react-marker-clustering';
import { MapLibreMapView2D, useMapLibreViewState } from '@mapconductor/react-for-maplibre';
<MapLibreMapView2D state={state}>
<MarkerClusterGroup
markers={markers}
minClusterSize={2}
clusterRadiusPx={80}
enableZoomAnimation
onClusterClick={cluster => console.log(cluster.count)}
/>
</MapLibreMapView2D>03 · Options
Option
Default
Description
clusterRadiusPx
90.0
Grouping distance in screen pixels. Smaller values split clusters more finely.
minClusterSize
3
Smallest number of markers rendered as a cluster; fewer stay individual.
clusterIconProvider
circle badge
Returns an icon for a given cluster size. Defaults to a circular badge.
onClusterClick
null
Receives cluster taps — typically used to zoom the camera in.
enableZoomAnimation
false
Toggles animating the expand/collapse while zooming; off by default. Duration is set separately via zoomAnimationDurationMs (default 300 ms).
04 · Performance
Smooth at thousands of markers
Clustering runs off the main thread and only recomputes when the camera settles.
SAMPLE
24,526