Add Pin Clustering support for Maps by jfversluis · Pull Request #33831 · dotnet/maui

jfversluis · 2026-02-02T10:15:14Z

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description

Adds Pin Clustering support for the Maps control on iOS/MacCatalyst and Android.

Fixes #11811

Changes

New API

Map.IsClusteringEnabled - Enable/disable pin clustering
Pin.ClusteringIdentifier - Group pins into named clusters
Map.ClusterClicked event - Fired when a cluster marker is tapped
ClusterClickedEventArgs - Contains the list of pins in the clicked cluster

iOS/MacCatalyst Implementation

Uses native MKClusterAnnotation support
Cluster clicks handled via DidSelectAnnotationView delegate
Automatic cluster management by MapKit

Android Implementation

Custom grid-based clustering algorithm (no external dependencies)
Clusters recalculate automatically when zoom level changes
Programmatic cluster icons showing pin count
Both cluster taps and individual pin taps work correctly

Testing

5 unit tests added for clustering functionality
Gallery sample page added (ClusteringGallery)
Manually verified on MacCatalyst and Android emulator

Copilot

Pull request overview

This PR adds pin clustering support to the MAUI Maps control for iOS/MacCatalyst and Android platforms. When enabled, pins that are close together are automatically grouped into cluster markers showing the count of pins. Users can tap clusters to zoom in and see individual pins.

Changes:

New API properties: Map.IsClusteringEnabled (bool), Pin.ClusteringIdentifier (string)
New event: Map.ClusterClicked with ClusterClickedEventArgs containing the pins and location
iOS/MacCatalyst uses native MKClusterAnnotation support (iOS 11+)
Android implements custom grid-based clustering algorithm with programmatic cluster icons
Sample gallery page demonstrates clustering with 30-100+ pins
5 unit tests added covering property defaults, event handling, and API implementation

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
PublicAPI.Unshipped.txt (all platforms)	Adds new public API entries for clustering properties and methods
IMap.cs	Adds IsClusteringEnabled property and ClusterClicked method to interface
IMapPin.cs	Adds ClusteringIdentifier property to interface
Map.cs	Implements IsClusteringEnabled bindable property and ClusterClicked event
Map.Impl.cs	Implements IMap.ClusterClicked to raise event and return handled status
Pin.cs	Adds ClusteringIdentifier bindable property with default constant
ClusterClickedEventArgs.cs	New event args class containing pins and location with Handled property
MauiMKMapView.cs	iOS implementation using MKClusterAnnotation with cluster view creation and zoom behavior
MapHandler.iOS.cs	iOS handler mapping for IsClusteringEnabled property
MapHandler.Android.cs	Android implementation with custom clustering algorithm, cluster icons, and zoom-based reclustering
MapHandler.*.cs (stubs)	NotImplementedException stubs for Windows, Tizen, Standard platforms
MapTests.cs	5 new unit tests for clustering properties, events, and API contracts
ClusteringGallery.xaml/.cs	Sample page demonstrating clustering with interactive controls
MapsGallery.cs	Navigation button added to access clustering gallery

Copilot · 2026-02-02T10:25:47Z

+
+			// Recalculate clusters when zoom level changes significantly
+			var currentZoom = _googleMap.CameraPosition.Zoom;
+			if (Math.Abs(currentZoom - _lastClusterZoom) > 0.5f)


The cluster recalculation threshold of 0.5 zoom levels may cause too-frequent reclustering, especially during smooth zoom animations. This could lead to performance issues and visual jitter. Consider increasing the threshold (e.g., 1.0 or 1.5) or implementing a debounce mechanism to avoid recalculating during continuous zoom operations.

Suggested change

if (Math.Abs(currentZoom - _lastClusterZoom) > 0.5f)

if (Math.Abs(currentZoom - _lastClusterZoom) > 1.0f)

Copilot · 2026-02-02T10:25:49Z

+			else if (OperatingSystem.IsIOSVersionAtLeast(11))
+			{
+				// Clear clustering identifier when disabled
+				mapPin.ClusteringIdentifier = null;
+			}


If clustering is disabled via toggling IsClusteringEnabled from true to false, this code clears the ClusteringIdentifier on pin views. However, if clustering is re-enabled later, pins will have lost their original ClusteringIdentifier values. Consider preserving the identifier in the underlying IMapPin data and only conditionally applying it to the view, rather than clearing it.

jfversluis · 2026-02-26T09:44:45Z

/azp run

azure-pipelines · 2026-02-26T09:45:03Z

Azure Pipelines successfully started running 3 pipeline(s).

kubaflo · 2026-02-26T15:51:27Z

Independent Code Review

Summary: Adds IsClusteringEnabled property, Pin.ClusteringIdentifier, ClusterClicked event, and IMap.ClusterClicked interface method. Includes sample and unit tests.

✅ What Looks Good

Well-designed API: IsClusteringEnabled on Map, ClusteringIdentifier on Pin, ClusterClicked event with Handled property
ClusterClickedEventArgs.Handled allows suppressing default zoom behavior — nice escape hatch
DefaultClusteringIdentifier constant avoids magic strings
Good test coverage (7 tests)

🔴 Issues

1. Android implements custom clustering, not Google Maps Utils
The diff shows MapCluster and manual cluster management fields, suggesting a custom implementation rather than using the widely-used android-maps-utils clustering library. Custom clustering implementations are notoriously difficult to get right (spatial indexing, animation, performance with 1000+ pins). Why not use the established library?

2. OfType<Pin>() cast in ClusterClicked loses non-Pin implementations

var controlPins = pins.OfType<Pin>().ToList();

This will silently drop any IMapPin implementations that aren't Pin. This could lose data.

3. No iOS implementation visible
MapKit has native clustering support via MKClusterAnnotation. Is it implemented? The diff was truncated but no iOS handler changes were shown in the visible portion.

4. Breaking interface change
Adding ClusterClicked and IsClusteringEnabled to IMap breaks any existing external implementations of the interface.

🟡 Nits

Sample uses _random as an instance field without seed — results aren't reproducible for debugging
Consider making DefaultClusteringIdentifier internal or at least documenting why it's public

github-actions · 2026-02-26T23:27:54Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 33831

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 33831"

jfversluis · 2026-02-26T23:28:09Z

Thanks for the review @kubaflo! Addressed the unresolved items and responding to other points:

Unresolved thread 1: Cluster recalculation threshold
Fixed — increased from 0.5 to 1.0 zoom levels to reduce jitter during smooth zoom animations.

Unresolved thread 2: iOS ClusteringIdentifier preservation
The concern is already handled by design. The \ClusteringIdentifier\ on the view (\MKAnnotationView) is transient — it's cleared when clustering is disabled. But the original value is preserved in the \IMapPin\ data (the model). When clustering is re-enabled, \GetPinForAnnotation()\ re-reads the identifier from the model and reapplies it to the view. Added a clarifying comment.

1. Custom clustering vs Google Maps Utils
Intentional design choice. Adding \�ndroid-maps-utils\ would introduce an external dependency with its own versioning/compatibility concerns. The custom grid-based approach is simpler, has zero external dependencies, and works well for the typical pin counts in mobile apps (~hundreds, not thousands). For very large datasets, we can recommend the Google Maps Utils library as a community solution.

2. OfType() cast
\Pin\ is the only public implementation of \IMapPin\ in MAUI. The \OfType()\ filters correctly for the public API surface. External \IMapPin\ implementations would need to be wrapped or use the \IMap.ClusterClicked\ interface method directly (which receives \IReadOnlyList).

3. Breaking interface change
These are new APIs in .NET 11. \IMap\ is an internal implementation detail between the control and handler — external implementations of \IMap\ are not a supported scenario. The interface is in \Microsoft.Maui.Maps\ namespace, not intended for external implementation.

kubaflo · 2026-02-27T00:27:32Z

🔍 Round 2 Review — PR #33831 (Pin Clustering)

Updated with author response analysis

✅ What Looks Good

ClusterClickedEventArgs.Handled property lets consumers suppress default zoom-to-cluster behavior — excellent UX pattern.
iOS implementation correctly uses MKClusterAnnotation and iOS 11+ version checks.
Pin.ClusteringIdentifier with DefaultClusteringIdentifier constant allows category-based clustering.
IsClusteringEnabled is a proper BindableProperty with XAML support.
Tests cover enable/disable toggle, cluster event firing, and default values.

⚠️ Issues & Author Responses

1. ~~Custom clustering vs Google Maps Utils~~ → Retracted
Author explains: android-maps-utils would introduce an external dependency with versioning/compatibility concerns. The custom grid-based approach is simpler, has zero external dependencies, and works for typical pin counts (~hundreds). For very large datasets, Google Maps Utils can be recommended as a community solution. Valid trade-off. ✅

2. OfType<Pin>() silently drops non-Pin IMapPin implementations → Softened
Author notes Pin is the only public IMapPin implementation in MAUI. External IMapPin implementations can use IMap.ClusterClicked directly (which receives IReadOnlyList<IMapPin>). This is technically valid, but the silent filtering without logging still feels like a subtle trap. Remaining suggestion: Consider logging a debug warning if pins.Count != controlPins.Count to help future developers who implement IMapPin understand why their pins are missing from cluster events.

3. ~~Breaking IMap/IMapPin interface changes~~ → Retracted
Author explains IMap is an internal contract between MAUI controls and handlers, not intended for external implementation. These are new .NET 11 APIs. Consistent with the handler pattern across all MAUI controls. ✅

4. ~~iOS clustering identifier lifecycle~~ → Retracted
Author clarifies: ClusteringIdentifier on the view (MKAnnotationView) is transient, but the value is preserved in the IMapPin model. When clustering is re-enabled, GetPinForAnnotation() re-reads the identifier from the model and reapplies it. Clarifying comment added. ✅

5. Thread safety of GetPinForAnnotation during cluster events → Still noted (minor, pre-existing pattern)
If AddPins/RemovePins race with OnClusterClicked iterating member annotations, the pin lookup could have issues. However, this is a pre-existing pattern throughout the map handler, not introduced by this PR. Low risk since handler mapper calls are UI-thread-serialized.

Summary

Author's responses were convincing across the board. The custom clustering approach over external dependencies is a valid architectural choice. The OfType<Pin>() filtering is the only point I still flag, and even that is a minor suggestion rather than a blocker. This PR is in good shape.

jfversluis · 2026-02-27T09:19:34Z

/azp run maui-pr

azure-pipelines · 2026-02-27T09:19:42Z

Azure Pipelines successfully started running 1 pipeline(s).

kubaflo · 2026-02-27T13:19:40Z

📋 Round 3 — PR #33831 (Pin Clustering) — Final Recommendation

One minor suggestion remains (logging when OfType<Pin>() filters out non-Pin implementations) but it's not a blocker — Pin is currently the only IMapPin implementation.

Recommendation: Merge when CI passes. The Build Analysis failure is infrastructure-level.

Merge order note: This PR modifies IMap.cs and IMapPin.cs interfaces. Merging after #33432 and #33792 would minimize rebase conflicts.

jfversluis · 2026-02-27T15:27:32Z

/rebase

- Add IsClusteringEnabled property to Map - Add ClusteringIdentifier property to Pin - Add ClusterClicked event with ClusterClickedEventArgs - Implement iOS clustering using MKClusterAnnotation - Add Android/Windows/Tizen stubs - Add unit tests for clustering functionality - Add ClusteringGallery sample page Fixes #11811

Implements built-in pin clustering for Android platform: - Grid-based clustering algorithm that groups nearby pins - Cluster radius adjusts based on zoom level - Cluster markers with visual count indicator - ClusterClicked event fires when cluster is tapped - Default behavior zooms to show cluster contents - Respects ClusteringIdentifier for grouping Implementation notes: - Uses custom clustering algorithm (no external library dependency) - Creates cluster markers with programmatic blue circle icons - Clusters dynamically adjust when IsClusteringEnabled changes

Switch from gesture recognizers to delegate-based handling for cluster clicks. MapKit intercepts taps before gesture recognizers, so cluster clicks need to be handled in the annotation selection delegate instead. - Remove gesture recognizer attachment for clusters - Handle cluster selection in MkMapViewOnAnnotationViewSelected - Disable callout for cluster markers (don't need them) - Deselect cluster after handling to allow re-selection

- Reduce cluster radius for more reasonable grouping - Add IOnCameraIdleListener to recalculate clusters when zoom changes - Clusters now properly split as user zooms in - Both cluster and individual pin clicks work correctly

- Fix clustering identifier to use Pin.DefaultClusteringIdentifier constant - Fix distance calculation with cos(latitude) adjustment for accuracy near poles - Dispose Paint/Canvas objects to prevent native memory leaks - Add null-safety for VirtualView.ClusterClicked - Clear stale cluster data when clustering is disabled - Document cluster radius constant - Fix iOS duplicate pins when toggling clustering (remove before re-add) - Fix nullable test variable - Await DisplayAlert in gallery sample

- Clear _clusters and _clusterMarkers when clustering is disabled - Use 'using' for Canvas and Paint to prevent native memory leaks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Replace Pin.DefaultClusteringIdentifier with literal string (handler can't reference Controls) - Remove non-existent RemovePins call (AddPins already clears annotations) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Increase cluster recalculation threshold from 0.5 to 1.0 zoom levels to reduce visual jitter during smooth zoom animations - Clarify iOS ClusteringIdentifier comment: view property is transient, IMapPin data preserves the original value for re-enablement Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dotnet-policy-service · 2026-02-27T18:15:21Z

🚨 API change(s) detected @davidortinau FYI

- Add Pin Clustering section to map.md with API reference, XAML/C# examples, and platform notes (iOS/Mac Catalyst via MKClusterAnnotation, Android grid-based, Windows not yet supported) - Update whats-new/dotnet-11.md with Map pin clustering entry and sample badge Upstream PR: dotnet/maui#33831 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 2, 2026 10:15

jfversluis added this to the .NET 11.0-preview1 milestone Feb 2, 2026

Copilot started reviewing on behalf of jfversluis February 2, 2026 10:15 View session

jfversluis mentioned this pull request Feb 2, 2026

Epic: Maps Control Improvements for .NET 11 #33787

Open

25 tasks

Copilot AI reviewed Feb 2, 2026

View reviewed changes

PureWeen modified the milestones: .NET 11.0-preview1, .NET 11.0-preview2 Feb 3, 2026

jfversluis mentioned this pull request Feb 19, 2026

Update Maps documentation for .NET 11 new features dotnet/docs-maui#3208

Closed

jfversluis force-pushed the feature/pin-clustering branch from aad6c21 to fd027fc Compare February 25, 2026 13:08

jfversluis force-pushed the feature/pin-clustering branch 2 times, most recently from 10f7786 to 497954b Compare February 26, 2026 09:35

kubaflo added area-controls-map Map / Maps copilot labels Feb 27, 2026

kubaflo approved these changes Feb 27, 2026

View reviewed changes

This was referenced Feb 27, 2026

Add Pin.ShowInfoWindow() and Pin.HideInfoWindow() methods #33985

Merged

Add MapStyle property for custom JSON map styling (Android) #33991

Merged

kubaflo enabled auto-merge (squash) February 27, 2026 13:32

jfversluis and others added 9 commits February 27, 2026 15:29

Fix Android pin clustering zoom behavior

0e7229b

- Reduce cluster radius for more reasonable grouping - Add IOnCameraIdleListener to recalculate clusters when zoom changes - Clusters now properly split as user zooms in - Both cluster and individual pin clicks work correctly

Address review feedback: clear clusters on disable, dispose Paint/Canvas

8962c3a

- Clear _clusters and _clusterMarkers when clustering is disabled - Use 'using' for Canvas and Paint to prevent native memory leaks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix nullable event handlers and indentation in clustering

d08f80b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions bot force-pushed the feature/pin-clustering branch from 1621e29 to d4ef0e7 Compare February 27, 2026 15:29

jfversluis disabled auto-merge February 27, 2026 18:14

jfversluis merged commit c7e6e46 into net11.0 Feb 27, 2026
20 of 27 checks passed

jfversluis deleted the feature/pin-clustering branch February 27, 2026 18:14

jfversluis modified the milestones: .NET 11.0-preview2, .NET 11.0-preview3 Feb 27, 2026

jfversluis added the t/breaking 💥 label Feb 27, 2026

dotnet deleted a comment from dotnet-policy-service bot Feb 27, 2026

This was referenced Feb 28, 2026

[repo-status] Daily Status Report - February 28, 2026 #34288

Closed

[repo-status] Daily Status Report - March 1, 2026 #34289

Closed

[repo-status] Daily Status Report - March 2, 2026 #34290

Closed

jfversluis mentioned this pull request Mar 3, 2026

Update Maps documentation for .NET 11 features dotnet/docs-maui#3212

Merged

davidortinau mentioned this pull request Mar 10, 2026

Add Map pin clustering sample for .NET MAUI 11 preview 3 dotnet/maui-samples#743

Merged

davidortinau mentioned this pull request Mar 10, 2026

Map pin clustering docs for .NET MAUI 11 dotnet/docs-maui#3222

Closed

github-actions bot locked and limited conversation to collaborators Mar 30, 2026

	if (Math.Abs(currentZoom - _lastClusterZoom) > 0.5f)
	if (Math.Abs(currentZoom - _lastClusterZoom) > 1.0f)

Conversation

jfversluis commented Feb 2, 2026

Description

Changes

New API

iOS/MacCatalyst Implementation

Android Implementation

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jfversluis commented Feb 26, 2026

Uh oh!

azure-pipelines bot commented Feb 26, 2026

Uh oh!

kubaflo commented Feb 26, 2026

Independent Code Review

✅ What Looks Good

🔴 Issues

🟡 Nits

Uh oh!

github-actions bot commented Feb 26, 2026

Uh oh!

jfversluis commented Feb 26, 2026

Uh oh!

kubaflo commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Round 2 Review — PR #33831 (Pin Clustering)

✅ What Looks Good

⚠️ Issues & Author Responses

Summary

Uh oh!

jfversluis commented Feb 27, 2026

Uh oh!

azure-pipelines bot commented Feb 27, 2026

Uh oh!

kubaflo commented Feb 27, 2026

📋 Round 3 — PR #33831 (Pin Clustering) — Final Recommendation

Uh oh!

jfversluis commented Feb 27, 2026

Uh oh!

Uh oh!

dotnet-policy-service bot commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kubaflo commented Feb 27, 2026 •

edited

Loading