maui-maps

name

maui-maps

description

Guidance for adding map controls, pins, polygons, polylines, geocoding, Google Maps API key configuration, and platform setup in .NET MAUI apps using Microsoft.Maui.Controls.Maps. USE FOR: "add map", "map control", "map pins", "polygons on map", "polylines", "geocoding", "Google Maps API key", "Microsoft.Maui.Controls.Maps", "map setup", "reverse geocoding", "map region". DO NOT USE FOR: getting device GPS coordinates (use maui-geolocation), custom drawing overlays (use maui-graphics-drawing), or location permissions only (use maui-permissions).

.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 <queries> 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;

<!-- ✅ Correct — namespace prefix in XAML -->
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
<maps:Map ... />

<!-- ❌ Wrong — bare <Map> is ambiguous -->
<Map ... />

Platform setup pitfalls

Android — API key must be inside <application>

<!-- ✅ Correct -->
<application ...>
  <meta-data android:name="com.google.android.geo.API_KEY"
             android:value="YOUR_GOOGLE_MAPS_KEY" />
</application>

<!-- ❌ Outside <application> — key is silently ignored -->

⚠️ Also required: Google Play Services version meta-data and <queries> 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

<!-- ✅ Correct — data-bound pins for dynamic collections -->
<maps:Map ItemsSource="{Binding Locations}">
    <maps:Map.ItemTemplate>
        <DataTemplate>
            <maps:Pin Label="{Binding Name}"
                      Address="{Binding Description}"
                      Location="{Binding Position}" />
        </DataTemplate>
    </maps:Map.ItemTemplate>
</maps:Map>

<!-- ❌ Wrong — manually adding pins in code-behind for data-driven scenarios -->

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 <application> in AndroidManifest.xml
• Android: Google Play Services version meta-data present
• Android 11+: <queries> 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