Syncfusion AI Assistant

How can I help you?

Getting started with MAUI Maps (SfMaps)

8 Jun 202615 minutes to read

This section explains the steps required to add the maps control with the shape layer and its elements such as data labels, tooltip, markers, and legends. This section covers only basic features needed to know to get started with Syncfusion® maps. Follow the steps below to add .NET MAUI Maps control to your project.

To get start quickly with our .NET MAUI Maps, you can check the below video.

Prerequisites

Before proceeding, ensure the following are set up:

  1. Install .NET 9 SDK or later.
  2. Set up a .NET MAUI environment with Visual Studio 2022 v17.12 or later.

Step 1: Create a New .NET MAUI Project

  1. Go to File > New > Project and choose the .NET MAUI App template.
  2. Name the project and choose a location. Then click Next.
  3. Select the .NET framework version and click Create.

Step 2: Install the Syncfusion .NET MAUI Maps NuGet Package

  1. In Solution Explorer, right-click the project and choose Manage NuGet Packages.
  2. Search for Syncfusion.Maui.Maps and install the latest version.
  3. Ensure the necessary dependencies are installed correctly, and the project is restored.

Step 3: Register the handler

The Syncfusion.Maui.Core NuGet is a dependent package for all Syncfusion® .NET MAUI controls. In the MauiProgram.cs file, register the handler for Syncfusion® core.

  • ~/MauiProgram.cs
    • using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using Microsoft.Maui.Controls.Compatibility;
using Microsoft.Maui.Controls.Hosting;
using Microsoft.Maui.Controls.Xaml;
using Syncfusion.Maui.Core.Hosting;

namespace MyProject
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
            .UseMauiApp<App>()
            .ConfigureSyncfusionCore()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

            return builder.Build();
        }
    }
}

    Step 4: Add .NET MAUI Maps control

    1. To initialize the control, import the Syncfusion.Maui.Maps namespace into your code.
    2. Initialize SfMaps 
    xmlns:map="clr-namespace:Syncfusion.Maui.Maps;assembly=Syncfusion.Maui.Maps"
    using Syncfusion.Maui.Maps;

    Create an instance for the maps control, and add it as content.

    <map:SfMaps>
  
</map:SfMaps>
    SfMaps map = new SfMaps();
	
this.Content = map;

    Prerequisites

    Before proceeding, ensure the following are set up:

    1. Install .NET 9 SDK or later.
    2. Set up a .NET MAUI environment with Visual Studio Code.
    3. Ensure that the .NET MAUI workloads are installed and configured as described here.

    Step 1: Create a New .NET MAUI Project

    1. Open the command palette by pressing Ctrl+Shift+P and type .NET:New Project and enter.
    2. Choose the .NET MAUI App template.
    3. Select the project location, type the project name and press Enter.
    4. Then choose Create project.

    Step 2: Install the Syncfusion .NET MAUI Maps NuGet Package

    1. Press Ctrl + ` (backtick) to open the integrated terminal in Visual Studio Code.
    2. Ensure you’re in the project root directory where your .csproj file is located.
    3. Run the command dotnet add package Syncfusion.Maui.Maps to install the Syncfusion® .NET MAUI Maps NuGet package.
    4. To ensure all dependencies are installed, run dotnet restore.

    Step 3: Register the handler

    The Syncfusion.Maui.Core NuGet is a dependent package for all Syncfusion® .NET MAUI controls. In the MauiProgram.cs file, register the handler for Syncfusion® core.

  • ~/MauiProgram.cs
    • using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using Microsoft.Maui.Controls.Compatibility;
using Microsoft.Maui.Controls.Hosting;
using Microsoft.Maui.Controls.Xaml;
using Syncfusion.Maui.Core.Hosting;

namespace MyProject
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
            .UseMauiApp<App>()
            .ConfigureSyncfusionCore()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

            return builder.Build();
        }
    }
}

    Step 4: Add .NET MAUI Maps control

    1. To initialize the control, import the Syncfusion.Maui.Maps namespace into your code.
    2. Initialize SfMaps 
    xmlns:map="clr-namespace:Syncfusion.Maui.Maps;assembly=Syncfusion.Maui.Maps"
    using Syncfusion.Maui.Maps;

    Create an instance for the maps control, and add it as content.

    <map:SfMaps>
  
</map:SfMaps>
    SfMaps map = new SfMaps();
	
this.Content = map;

    Prerequisites

    Before proceeding, ensure the following are set up:

    1. Install .NET 9 SDK or later.
    2. Set up a .NET MAUI environment with JetBrains Rider 2024.3 or later.
    3. Make sure the MAUI workloads are installed and configured as described here.

    Step 1: Create a new .NET MAUI Project

    1. Go to File > New Solution, Select .NET (C#) and choose the .NET MAUI App template.
    2. Enter the Project Name, Solution Name, and Location.
    3. Select the .NET framework version and click Create.

    Step 2: Install the Syncfusion® MAUI Maps NuGet Package

    1. In Solution Explorer, right-click the project and choose Manage NuGet Packages.
    2. Search for Syncfusion.Maui.Maps and install the latest version.
    3. Ensure the necessary dependencies are installed correctly, and the project is restored. If not, Open the Terminal in Rider and manually run: dotnet restore

    Step 3: Register the handler

    The Syncfusion.Maui.Core NuGet is a dependent package for all Syncfusion® .NET MAUI controls. In the MauiProgram.cs file, register the handler for Syncfusion® core.

  • ~/MauiProgram.cs
    • using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using Microsoft.Maui.Controls.Compatibility;
using Microsoft.Maui.Controls.Hosting;
using Microsoft.Maui.Controls.Xaml;
using Syncfusion.Maui.Core.Hosting;

namespace MyProject
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
            .UseMauiApp<App>()
            .ConfigureSyncfusionCore()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

            return builder.Build();
        }
    }
}

    Step 4: Add .NET MAUI Maps control

    1. To initialize the control, import the Syncfusion.Maui.Maps namespace into your code.
    2. Initialize SfMaps 
    xmlns:map="clr-namespace:Syncfusion.Maui.Maps;assembly=Syncfusion.Maui.Maps"
    using Syncfusion.Maui.Maps;

    Create an instance for the maps control, and add it as content.

    <map:SfMaps>
  
</map:SfMaps>
    SfMaps map = new SfMaps();
	
this.Content = map;

    Step 5: Set GeoJSON data or shapefile for shape layer from various source

    The Layer in SfMaps holds MapShapeLayer. The actual geographical rendering is done in the each MapShapeLayer. The ShapesSource property of the MapShapeLayer is of type MapSource. The ShapesSource can be set as the .json source or shapefile.

    IMPORTANT

    The Mercator projection is the default projection in the maps.

    The ShapesSource property is used to load shapes from different sources:

    • FromFile returns a MapSource that reads a shape source from a local file.
    • FromUri returns an MapSource that downloads and reads a shape source from a specified URI.
    • FromResource returns a MapSource that reads a shape source file embedded in an assembly.
    • FromStream returns a MapSource that reads a shape source from a stream that supplies source data.

    Loading a local file

    SfMaps provides support to load the json data or shapefile from local path.

    public MainPage()
{
    InitializeComponent();
    SfMaps map = new SfMaps();
    MapShapeLayer layer = new MapShapeLayer();
    layer.ShapesSource = MapSource.FromFile(@"D:\MyProject\usa_state.shp");
    map.Layer = layer;
    this.Content = map;
}

    The MapSource.FromFile method requires a string argument, and returns a new MapSource object that reads the data from the shape source file. There’s also an implicit conversion operator that enables the filename to be specified as a string argument to the ShapesSource property

    <map:SfMaps>
    <map:SfMaps.Layer>
        <map:MapShapeLayer ShapesSource="D:\MyProject\usa_state.shp" />
    </map:SfMaps.Layer>
</map:SfMaps>
    public MainPage()
{
    InitializeComponent();
    SfMaps map = new SfMaps();
    MapShapeLayer layer = new MapShapeLayer();
    layer.ShapesSource = MapSource.FromFile(@"D:\MyProject\usa_state.shp");
    map.Layer = layer;
    this.Content = map;
}

    Load a remote file

    SfMaps provides support to load the json data or shapefile from the uri.

    public MainPage()
{
    InitializeComponent();
    SfMaps map = new SfMaps();
    MapShapeLayer layer = new MapShapeLayer();
    layer.ShapesSource = MapSource.FromUri(new Uri("https://cdn.syncfusion.com/maps/map-data/world-map.json"));
    map.Layer = layer;
    this.Content = map;
}

    The MapSource.FromUri method requires a Uri argument, and returns a new MapSource object that reads the shape source from the Uri. There’s also an implicit conversion for string-based URIs.

    <map:SfMaps>
    <map:SfMaps.Layer>
        <map:MapShapeLayer ShapesSource="https://cdn.syncfusion.com/maps/map-data/world-map.json" />
    </map:SfMaps.Layer>
</map:SfMaps>
    public MainPage()
{
    InitializeComponent();
    SfMaps map = new SfMaps();
    MapShapeLayer layer = new MapShapeLayer();
    layer.ShapesSource = MapSource.FromUri(new Uri("https://cdn.syncfusion.com/maps/map-data/world-map.json"));
    map.Layer = layer;
    this.Content = map;
}

    Load an embedded file

    • Embedded sources are loaded based on their resource ID, which is compromised of the name of the project and its location in the project.
    • You can load both json data and shapefile.
    • For example, placing australia.json in the root folder of a project named MyProject will result in a resource ID of MyProject.australia.json. Similarly, placing world1.shp in the Assets folder of a project named MyProject will result in a resource ID of MyProject.Assets.world1.shp
    • Right-click the added shapefile, and navigate to properties.
    • Choose the EmbeddedResource option under BuildAction of respective shapefile.

    NOTE

    You can get the australia.json file here.

    public MainPage()
{
    InitializeComponent();
    SfMaps map = new SfMaps();
    MapShapeLayer layer = new MapShapeLayer();
    layer.ShapesSource = MapSource.FromResource("MyProject.australia.json");
    map.Layer = layer;
    this.Content = map;
}

    Loading from stream

    SfMaps provides support to load the json data or shapefile as bytes from stream.

    public MainPage()
{
    InitializeComponent();
    SfMaps map = new SfMaps();
    MapShapeLayer layer = new MapShapeLayer();
    Assembly assembly = Application.Current?.GetType().GetTypeInfo().Assembly;
    var jsonStream = assembly?.GetManifestResourceStream("MyProject.Assets.australia.json");
    layer.ShapesSource = MapSource.FromStream(jsonStream);
    map.Layer = layer;
    this.Content = map;
}

    The following screenshot illustrates the result of the above code.

    .NET MAUI Maps basic view.

    NOTE

    • Get the complete getting started sample from GitHub link.
    • You can refer to our .NET MAUI Maps feature tour page for its groundbreaking feature representations. You can also explore our .NET MAUI Maps Example that shows you how to render the Maps in .NET MAUI.