map_marker_cluster library
Modern, lightweight, customizable, and provider-agnostic map marker clustering library for Flutter.
Built purely on top of package:flutter/widgets.dart with zero third-party
dependencies, map_marker_cluster provides:
- High-performance
O(n)spatial hash clustering (ClusterEngine) with pan-stable world-coordinate caching and antimeridian-safe centroids. - Provider-agnostic overlay (ClusterMapOverlay) that layers cleanly on
top of
flutter_map,google_maps_flutter, Mapbox, MapLibre, or custom map canvases. - All-in-one interactive map widget (InteractiveClusterMap) with pan, pinch/wheel focal zoom, animated camera transitions, and a procedural VectorMapBackdrop.
- Spiderfy radial & Archimedean spiral layouts (SpiderfyLayoutEngine, SpiderfyOverlay) for co-located or dense clusters.
- Modern, customizable theming (ClusterThemeData) with 4 curated
presets (
modern,dark,minimal,emerald), animated pulsing halos, vector pins, and floating callout cards.
Classes
- ClusterCameraTransition
- Describes an animated camera transition requested via ClusterController.animateTo.
-
ClusterController<
T> - Reactive controller managing markers, viewport state, clustering output, selection, filtering, and spiderfy interactions.
-
ClusterEngine<
T> - High-performance, pan-stable spatial marker clustering engine.
-
ClusterMapOverlay<
T> -
Provider-agnostic marker clustering overlay that can be placed directly
above any Flutter map widget (
flutter_map,google_maps_flutter,apple_maps_flutter, Mapbox, MapLibre, or custom canvas maps) inside a Stack. -
ClusterMarker<
T> -
A data-carrying map marker that can be grouped into clusters by
ClusterEngineand rendered byClusterMapOverlayorInteractiveClusterMap. -
ClusterNode<
T> - Represents either a single unclustered ClusterMarker or a group of multiple markers merged into one cluster at the current zoom level.
- ClusterOptions
- Configuration options controlling clustering geometry, viewport culling, zoom limits, and spiderfy behavior.
- ClusterThemeData
- Complete visual theme governing default cluster badges, individual marker pins, spiderfy legs, floating callout cards, and motion curves.
- ClusterTier
- Visual styling for a single size/density bucket of cluster badges.
-
DefaultClusterBadge<
T> - Default modern multi-layered cluster badge featuring diagonal gradients, translucent pulsing halos, specular edge lighting, and tactile hover/press micro-interactions.
-
DefaultMarkerCallout<
T> - Default floating modern callout card displayed above (or below when near the top edge) a selected ClusterMarker.
-
DefaultMarkerPin<
T> - Default crisp vector map pin rendered via CustomPaint with zero icon-font or Material dependencies.
- GeoBounds
- An immutable axis-aligned geographic bounding box defined by southWest and northEast corners.
- GeoPoint
- An immutable geographic coordinate represented by latitude and longitude in decimal degrees (WGS-84).
-
InteractiveClusterMap<
T> - All-in-one interactive map widget with built-in smooth pan, focal-point pinch/wheel zoom, double-tap zoom, animated camera transitions, optional floating map controls, and modern marker clustering.
- MapProjection
- Contract for converting between geographic coordinates (GeoPoint), continuous world pixel coordinates at a given zoom level, and screen pixels within a MapViewport.
- MapViewport
- Snapshot of a map camera and viewport dimensions used to project markers and compute clusters.
-
SpatialHashGrid<
T> -
A lightweight 2D spatial hash grid that accelerates nearest-neighbor
lookups from
O(n^2)to amortizedO(n). -
SpiderfiedItem<
T> - Positioned marker element inside an active spiderfy expansion.
-
SpiderfyLayout<
T> - Computed radial/spiral geometry for a spiderfied ClusterNode.
- SpiderfyLayoutEngine
- Computes non-overlapping circular or Archimedean spiral positions for markers fanned out from a cluster center.
-
SpiderfyOverlay<
T> - Animated overlay that renders curved or straight spider legs connecting a cluster's anchor to its radially fanned-out markers.
- VectorMapBackdrop
- Lightweight, zero-dependency procedural vector map background synchronized 1:1 with MapViewport world coordinates (pan, zoom, and rotation).
- VectorMapStyle
- Color palette configuring the built-in lightweight procedural VectorMapBackdrop.
- WebMercatorProjection
-
Standard EPSG:3857 Spherical Web Mercator projection compatible with
OpenStreetMap, Google Maps, Mapbox, MapLibre, Apple Maps, and
flutter_map.
Enums
- ClusterTapBehavior
- Determines how ClusterMapOverlay and InteractiveClusterMap respond when the user taps a cluster badge.
- SpiderfyShape
- Geometry used when fanning out spiderfied markers around a cluster center.
Constants
- maxMercatorLatitude → const double
- Maximum latitude supported by standard Web Mercator projection.
Functions
-
defaultClusterCountFormatter(
int count) → String -
Formats a cluster's marker
countinto a compact human-readable label (for example:42,1.2k,18k,2.4M).
Typedefs
-
CalloutWidgetBuilder<
T> = Widget Function(BuildContext context, ClusterMarker< T> marker, VoidCallback onClose, ClusterThemeData theme) -
Builder callback for rendering a custom floating callout card above a
selected
marker. - CameraAnimationHandler = void Function(ClusterCameraTransition transition)
- Callback used by an attached interactive map widget to execute smooth camera animations requested through ClusterController.
-
ClusterTapCallback<
T> = void Function(ClusterNode< T> cluster) - Callback invoked when a user taps a cluster badge.
-
ClusterWidgetBuilder<
T> = Widget Function(BuildContext context, ClusterNode< T> cluster, ClusterThemeData theme) - Builder callback for rendering a custom cluster badge widget.
- MapLayerBuilder = Widget Function(BuildContext context, MapViewport viewport)
-
Builder callback for providing a custom background map layer (such as
flutter_map,google_maps_flutter, custom tiles, or vector canvas) synchronized withviewport. -
MarkerFilter<
T> = bool Function(ClusterMarker< T> marker) - Predicate used to filter which ClusterMarker entries are active.
-
MarkerTapCallback<
T> = void Function(ClusterMarker< T> marker) - Callback invoked when a user taps an individual marker (either standalone or inside a spiderfied expansion).
-
MarkerWidgetBuilder<
T> = Widget Function(BuildContext context, ClusterMarker< T> marker, ClusterThemeData theme, {required bool isSelected}) - Builder callback for rendering a custom individual marker widget.