Getting started with .NET MAUI Maps (SfMaps)

15 Jul 20269 minutes to read

NOTE

Prerequisite: Ensure that the required NuGet package is installed, the necessary namespaces are imported, and the Maps control is properly configured in your application. For detailed setup and configuration instructions, refer to the Getting Started guide.

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 started quickly with our .NET MAUI Maps, you can check the below video.

Prerequisites

Before proceeding, ensure the following are set up:

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

Step 1: Create a new .NET MAUI project

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

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

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

Prerequisites

Before proceeding, ensure the following are set up:

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

Step 1: Create a new .NET MAUI project

Open the Command Palette by pressing Ctrl+Shift+P and type .NET:New Project and press Enter.
Choose the .NET MAUI App template.
Select the project location, type the project name and press Enter.
Then, choose Create project.

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

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

Prerequisites

Before proceeding, ensure the following are set up:

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

Step 1: Create a new .NET MAUI project

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

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

In Solution Explorer, right-click the project and choose Manage NuGet Packages.
Search for Syncfusion.Maui.Maps and install the latest version.
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 Syncfusion handler

Make sure to add the namespace.

C#
using Syncfusion.Maui.Core.Hosting;

C#
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureSyncfusionCore();

    //code omitted for brevity

    return builder.Build();
}

Step 4: Import the Maps namespace

Add the following namespace in your XAML or C#.

XAML
C#
<ContentPage xmlns:map="clr-namespace:Syncfusion.Maui.Maps;assembly=Syncfusion.Maui.Maps">
 
</ContentPage>
using Syncfusion.Maui.Maps;

Step 5: Add a Maps component

Initialize the SfMaps and add a Layer which contains MapShapeLayer elements. The actual geographical rendering is done in 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.

Set GeoJSON data or shapefile for the shape layer from various sources

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 a 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.

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.

NOTE

When using absolute file paths like D:\MyProject\usa_state.shp, ensure cross-platform compatibility. On iOS and Android, use the app data directory or FileSystem.AppDataDirectory to construct valid paths.

XAML
C#
<map:SfMaps>
    <map:SfMaps.Layer>
        <map:MapShapeLayer ShapesSource="D:\MyProject\usa_state.shp" />
    </map:SfMaps.Layer>
</map:SfMaps>
SfMaps map = new SfMaps();
MapShapeLayer layer = new MapShapeLayer();
layer.ShapesSource = MapSource.FromFile(@"D:\MyProject\usa_state.shp");
map.Layer = layer;

Loading a remote file

SfMaps provides support to load the JSON data or shapefile from the URI.

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.

NOTE

To download remote GeoJSON or shapefile data on Android, ensure the INTERNET permission is declared in the AndroidManifest.xml file.

XAML
C#
<map:SfMaps>
    <map:SfMaps.Layer>
        <map:MapShapeLayer ShapesSource="https://cdn.syncfusion.com/maps/map-data/world-map.json" />
    </map:SfMaps.Layer>
</map:SfMaps>
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;

Loading an embedded file

Embedded sources are loaded based on their resource ID, which is composed 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.

To set the build action for the embedded file, follow these steps:

Right-click the added shapefile or JSON file, and navigate to properties.
Choose the EmbeddedResource option under Build Action of the respective file.

NOTE

The resource ID differs based on the folder location. For a file in the project root, the resource ID is MyProject.australia.json. For a file in the Assets folder, the resource ID is MyProject.Assets.australia.json. Ensure the resource ID used in code matches the file’s folder location.

NOTE

You can get the australia.json file here.

XAML
C#
<map:SfMaps>
    <map:SfMaps.Layer>
        <map:MapShapeLayer ShapesSource="MyProject.australia.json" />
    </map:SfMaps.Layer>
</map:SfMaps>
SfMaps map = new SfMaps();
MapShapeLayer layer = new MapShapeLayer();
layer.ShapesSource = MapSource.FromResource("MyProject.australia.json");
map.Layer = layer;

Loading from stream

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

The GetManifestResourceStream method returns null if the resource name is not found. For more reliable assembly resolution, use typeof(App).GetTypeInfo().Assembly to get the project assembly.

C#
SfMaps map = new SfMaps();
MapShapeLayer layer = new MapShapeLayer();
var assembly = typeof(App).GetTypeInfo().Assembly;
var jsonStream = assembly?.GetManifestResourceStream("MyProject.Assets.australia.json");
layer.ShapesSource = MapSource.FromStream(jsonStream);
map.Layer = layer;

The following screenshot illustrates the result of the above code.

.NET MAUI Maps basic view.

You can download the Maps Getting Started sample from GitHub.

NOTE

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.

Search docs

Ask Syncfusion AI Assistant

Search docs

Ask Syncfusion AI Assistant

Getting started with .NET MAUI Maps (SfMaps)

Prerequisites

Step 1: Create a new .NET MAUI project

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

Prerequisites

Step 1: Create a new .NET MAUI project

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

Prerequisites

Step 1: Create a new .NET MAUI project

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

Step 3: Register Syncfusion handler

Step 4: Import the Maps namespace

Step 5: Add a Maps component

Set GeoJSON data or shapefile for the shape layer from various sources

Loading a local file

Loading a remote file

Loading an embedded file

Loading from stream

Getting started with .NET MAUI Maps (SfMaps)

Prerequisites

Step 1: Create a new .NET MAUI project

Step 2: Install the Syncfusion® MAUI Maps NuGet package

Prerequisites

Step 1: Create a new .NET MAUI project

Step 2: Install the Syncfusion® MAUI Maps NuGet package

Prerequisites

Step 1: Create a new .NET MAUI project

Step 2: Install the Syncfusion® MAUI Maps NuGet package

Step 3: Register Syncfusion handler

Step 4: Import the Maps namespace

Step 5: Add a Maps component

Set GeoJSON data or shapefile for the shape layer from various sources

Loading a local file

Loading a remote file

Loading an embedded file

Loading from stream

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

Step 2: Install the Syncfusion^® MAUI Maps NuGet package

Step 2: Install the Syncfusion^® MAUI Maps NuGet package