Maui Maps

.NET MAUI Maps

Common gotchas

| Issue | Fix | |---|---| | Map is blank on Android | Google Maps API key missing or wrong in AndroidManifest.xml | | Map crashes on startup | .UseMauiMaps() not called in MauiProgram.cs | | Map type ambiguous | Conflicts with Microsoft.Maui.ApplicationModel.Map — add namespace alias | | Map doesn't show on Windows | Windows has no native support — must use CommunityToolkit.Maui.Maps | | User location dot missing | IsShowingUser="True" set but location permission not granted | | Android 11+ can't launch external map app | Missing ` for geo` scheme in manifest |

⚠️ Name conflict — always alias

Microsoft.Maui.Controls.Maps.Map conflicts with Microsoft.Maui.ApplicationModel.Map. This causes confusing compile errors.

// ✅ Correct — explicit alias
using Map = Microsoft.Maui.Controls.Maps.Map;

xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"

Platform setup pitfalls

Android — API key must be inside ``

⚠️ Also required: Google Play Services version meta-data and ` for geo scheme on API 30+ (see references/maps-api.md`).

iOS / Mac Catalyst

⚠️ Without NSLocationWhenInUseUsageDescription in Info.plist, location permission is denied without prompt.

Windows — no native support

Must add CommunityToolkit.Maui.Maps + Bing key. Use conditional package reference and #if WINDOWS for setup.

MauiProgram.cs — don't forget UseMauiMaps

// ✅ Required — without this, Map control throws at runtime
builder.UseMauiMaps();

// ❌ Forgetting this causes "No registered handler for Map" crash

Performance tips

• ⚠️ Don't add hundreds of pins directly — use ItemsSource with data binding for large pin sets.
• Set initial region with MoveToRegion() to avoid the default world view zoom animation.
• Avoid frequent MoveToRegion() calls — each triggers a map animation; debounce if driven by data changes.

Data-bound pins — do this for dynamic data

Decision framework

| Need | Approach | |---|---| | Basic map with pins | Map control + Pins.Add() or ItemsSource binding | | Map with shapes | MapElements — Polygon, Polyline, Circle | | Address → coordinates | Geocoding.Default.GetLocationsAsync(address) | | Coordinates → address | Geocoding.Default.GetPlacemarksAsync(lat, lon) | | Custom map overlays | Use handlers to access native map APIs | | Windows support | Must add CommunityToolkit.Maui.Maps + Bing key |

Quick checklist

• [ ] NuGet: Microsoft.Maui.Controls.Maps added
• [ ] .UseMauiMaps() called in MauiProgram.cs
• [ ] Android: Google Maps API key inside ` in AndroidManifest.xml`
• [ ] Android: Google Play Services version meta-data present
• [ ] Android 11+: `` for geo scheme added
• [ ] iOS/Mac: NSLocationWhenInUseUsageDescription in Info.plist
• [ ] Windows: CommunityToolkit.Maui.Maps + Bing Maps key (conditional)
• [ ] Namespace alias added to avoid Map type conflict

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davidortinau
• Source: davidortinau/maui-skills
• License: MIT

Install and usage instructions live in the source repository linked above.