If you've ever tried to display dozens or hundreds of pins on a map, you know the struggle: a cluttered mess that's nearly impossible to interact with. Starting with .NET MAUI 11 Preview 3, the Map control includes built-in pin clustering on Android, iOS, and Mac Catalyst. This guide answers the most common questions about this feature, from enabling it to handling cluster taps.
- What is pin clustering and why is it needed?
- How do I enable pin clustering in .NET MAUI Maps?
- Can I group different types of pins into separate clusters?
- How do I handle when a user taps on a cluster?
- Are there any platform-specific differences in clustering?
- How does the clustering algorithm work for performance?
- Where can I find examples and full documentation?
What is pin clustering and why is it needed?
Pin clustering is a technique that automatically groups nearby pins into a single cluster marker when you zoom out on a map. As you zoom in, those clusters expand to reveal individual pins. This solves a common pain point: when a map is loaded with many pins (tens, hundreds, or more), they overlap and become impossible to tap or distinguish. Clustering keeps the map clean and usable. This feature was a long-requested enhancement (issue #11811) because it's essential for any app that displays a lot of location data, such as store locators, event maps, or real estate listings. With clustering, users can quickly see the density of pins without zooming in and out repeatedly. It provides a polished, production-ready experience out of the box in .NET MAUI Maps.
How do I enable pin clustering in .NET MAUI Maps?
Enabling pin clustering is remarkably simple. You only need to set a single property on the Map control: IsClusteringEnabled="True". For example:
<maps:Map IsClusteringEnabled="True" />That's all it takes. Once enabled, any Pin objects added to the map will be automatically grouped into clusters when they are close together at the current zoom level. Each cluster displays a count badge indicating how many pins it contains. As the user zooms in, clusters break apart, and eventually individual pins appear. The default clustering algorithm handles all the logic, so you don't need to write any additional code. This feature works on Android, iOS, and Mac Catalyst starting from .NET MAUI 11 Preview 3.
Can I group different types of pins into separate clusters?
Absolutely. Not all pins are the same—you might want coffee shops to cluster independently from parks, or hotels separately from attractions. The ClusteringIdentifier property on the Pin class lets you control which pins group together. Pins that share the same identifier form their own clusters, while those with different identifiers remain in independent clusters even if they are geographically close. Pins without an identifier all share a default group. Example:
map.Pins.Add(new Pin
{
Label = "Pike Place Coffee",
Location = new Location(47.6097, -122.3331),
ClusteringIdentifier = "coffee"
});
map.Pins.Add(new Pin
{
Label = "Occidental Square",
Location = new Location(47.6064, -122.3325),
ClusteringIdentifier = "parks"
});In this case, coffee pins cluster among themselves, and parks cluster separately. This is perfect for layered map visualizations where different categories should remain distinct.
How do I handle when a user taps on a cluster?
When a user taps a cluster marker, the ClusterClicked event fires. The event argument (ClusterClickedEventArgs) provides access to the pins in that cluster, the cluster's geographic center (Location), and a Handled property. By default, tapping a cluster zooms the map in to show the individual pins. If you want to override that behavior, set e.Handled = true. Here's a typical handler that shows an alert with the pin names:
map.ClusterClicked += async (sender, e) =>
{
string names = string.Join("\n", e.Pins.Select(p => p.Label));
await DisplayAlert(
$"Cluster ({e.Pins.Count} pins)",
names,
"OK");
// Suppress default zoom-to-cluster behavior:
// e.Handled = true;
};This allows you to display custom information, navigate to a detail page, or perform any other action when a cluster is tapped.
Are there any platform-specific differences in clustering?
Yes, but the API is consistent across platforms. Under the hood, Android and iOS/Mac Catalyst use different algorithms to achieve clustering. On Android, .NET MAUI employs a custom grid-based algorithm that recalculates clusters whenever the zoom level changes. It requires no external dependencies. On iOS and Mac Catalyst, clustering leverages the native MKClusterAnnotation support from Apple's MapKit, which provides smooth, platform-native cluster animations and behavior. Both approaches deliver the same user experience: pins are grouped into clusters with count badges, and as you zoom, clusters expand naturally. The API (enabling with IsClusteringEnabled, using ClusteringIdentifier, and handling ClusterClicked) works identically on all platforms. This means you write the same code and get optimized performance on each device.
How does the clustering algorithm work for performance?
The clustering algorithm is designed to be efficient even with hundreds or thousands of pins. On Android, the grid-based algorithm recalculates clusters only when needed (i.e., when the zoom level changes), which minimizes computational overhead. The algorithm groups pins based on their geographic proximity relative to the current zoom level. As you zoom in, the grid cells become smaller, causing clusters to break apart into smaller groups or individual pins. This approach ensures smooth panning and zooming without lag. On iOS and Mac Catalyst, the native MapKit clustering is highly optimized by Apple, using quadtree or similar spatial indexing under the hood. In either case, you don't need to worry about performance tuning—the framework handles it. For very large datasets, you can further optimize by only adding pins that are visible in the current map view, but clustering alone handles most scenarios effectively.
Where can I find examples and full documentation?
Microsoft provides a dedicated sample in the maui-samples repository. Look for the Maps sample, which includes a new Clustering page demonstrating pin clustering with multiple clustering groups and cluster tap handling. This is an excellent starting point to see clustering in action. For the full API reference, detailed properties, method explanations, and additional examples, visit the official Maps documentation on Microsoft Learn. Also, make sure you're using .NET MAUI 11 Preview 3 or later to access this feature. To get started, install the latest .NET 11 Preview 3 and update your NuGet packages. You can then easily add clustering to your map-heavy app with just a few lines of code. Happy mapping!