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 ClusterEngine and rendered by ClusterMapOverlay or InteractiveClusterMap.
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 amortized O(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 count into 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 with viewport.
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.