ContextQMD
Back to Maui

Microsoft.Maui.Controls.Maps

src/Controls/Maps/README.md

10.0.516.6 KB
Original Source

Microsoft.Maui.Controls.Maps

Microsoft.Maui.Controls.Maps brings an easy-to-use map control to .NET MAUI apps so you can display maps, drop pins, draw shapes, and react to user interactions on Android and iOS from one shared codebase. (Windows implementation is not available yet.)

πŸš€ Get started

  1. Install the package

    bash
    dotnet add package Microsoft.Maui.Controls.Maps

  2. Enable Maps in MauiProgram.cs

    csharp
    var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiMaps(); // registers map handlers

  3. Add platform credentials

    • Android: Add your Google Maps API key to Platforms/Android/AndroidManifest.xml
      xml
      <application>
    <meta-data android:name="com.google.android.geo.API_KEY"
               android:value="YOUR_API_KEY_HERE" />
</application>
    • iOS: No additional keys required for the built-in map provider.
    • Windows: The Maps control is currently not implemented on Windows. For updates, see this tracking link.

  4. Place a map in your page

    xml

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps" xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials"> maps:Map maps:Map.Pins <maps:Pin Label="Downtown" Address="Main Street" Type="Place"> maps:Pin.Location sensors:Location <x:Arguments> <x:Double>47.6205</x:Double> <x:Double>-122.3493</x:Double> </x:Arguments> </sensors:Location> </maps:Pin.Location> </maps:Pin> </maps:Map.Pins> </maps:Map> </ContentPage>


## 🧭 Features at a glance

- **Pins**: Labels, addresses, pin types, custom images, and tap handling via `PinClicked`.
- **Shapes**: Draw **polygons**, **polylines**, and **circles** to outline areas or routes.
- **Map interactions**: Handle `MapClicked`, move the camera/region, and programmatically add or remove map elements at runtime.
- **Map display**: Switch map types (e.g., Street, Satellite, Hybrid) and control gesture support (scroll, zoom, rotate).
- **User location**: Show the user’s current location with `IsShowingUser` (platform location permission required).

### Samples: pins and shapes

```xml
<maps:Map xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
       xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials"
       MapType="Hybrid" MapClicked="OnMapClicked">
 <maps:Map.Pins>
     <maps:Pin Label="Office" Type="Place">
         <maps:Pin.Location>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.6424</x:Double>
                     <x:Double>-122.3219</x:Double>
                 </x:Arguments>
             </sensors:Location>
         </maps:Pin.Location>
     </maps:Pin>
 </maps:Map.Pins>

 <maps:Map.MapElements>
     <maps:Polygon StrokeColor="Red" FillColor="#40FF0000" StrokeWidth="4">
         <maps:Polygon.Geopath>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.642</x:Double>
                     <x:Double>-122.323</x:Double>
                 </x:Arguments>
             </sensors:Location>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.643</x:Double>
                     <x:Double>-122.326</x:Double>
                 </x:Arguments>
             </sensors:Location>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.640</x:Double>
                     <x:Double>-122.327</x:Double>
                 </x:Arguments>
             </sensors:Location>
         </maps:Polygon.Geopath>
     </maps:Polygon>

     <maps:Polyline StrokeColor="DodgerBlue" StrokeWidth="6">
         <maps:Polyline.Geopath>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.639</x:Double>
                     <x:Double>-122.330</x:Double>
                 </x:Arguments>
             </sensors:Location>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.640</x:Double>
                     <x:Double>-122.335</x:Double>
                 </x:Arguments>
             </sensors:Location>
         </maps:Polyline.Geopath>
     </maps:Polyline>

     <maps:Circle StrokeColor="Green" FillColor="#40008000" StrokeWidth="3">
         <maps:Circle.Center>
             <sensors:Location>
                 <x:Arguments>
                     <x:Double>47.641</x:Double>
                     <x:Double>-122.329</x:Double>
                 </x:Arguments>
             </sensors:Location>
         </maps:Circle.Center>
         <maps:Circle.Radius>
             <maps:Distance>
                 <x:Arguments>
                     <x:Double>200</x:Double>
                 </x:Arguments>
             </maps:Distance>
         </maps:Circle.Radius>
     </maps:Circle>
 </maps:Map.MapElements>
</maps:Map>

Samples: interactions and map modes

csharp
// In code-behind
void OnMapClicked(object sender, MapClickedEventArgs e)
{
    // Drop a pin where the user tapped
    var map = (Map)sender;
    map.Pins.Add(new Pin
    {
        Label = "Dropped pin",
        Type = PinType.Place,
        Location = e.Location
    });

    // Move/zoom to the tapped location
    map.MoveToRegion(MapSpan.FromCenterAndRadius(e.Location, Distance.FromMeters(500)));
}

// Toggle map display mode
void ToggleMapType(Map map) =>
    map.MapType = map.MapType == MapType.Street ? MapType.Satellite : MapType.Street;

// Common runtime toggles
void EnableLocationAndTraffic(Map map)
{
    map.IsShowingUser = true;      // requires location permission on the device
    map.IsTrafficEnabled = true;   // show live traffic where supported
}

πŸ“š Learn more