.NET MAUI Documentation

Displaying Images

The primary control for displaying images in .NET MAUI is the

Image

Loading from Embedded Resources

Embedding images directly into your project is the recommended approach for platform-agnostic image handling. These images are compiled into your application assembly.

To embed an image:

1. Add the image file to your project (e.g., in an Resources/Images folder).
2. Right-click the image file in the Solution Explorer, select Properties, and set the Build Action to MauiImage.

You can then reference the image using its filename:

<Image Source="my_logo.png" />

For images in subfolders within Resources/Images, use a forward slash:

<Image Source="Images/Icons/app_icon.png" />

Loading from Local Files

You can also load images from the device's file system. This is useful for images captured by the camera or downloaded by the user.

<Image Source="{Binding ImagePath}" />

In your C# code-behind or ViewModel, ensure ImagePath is a string representing the file path.

Loading from URIs

Remote images can be loaded directly from web URLs. .NET MAUI handles asynchronous downloading and caching.

<Image Source="https://docs.microsoft.com/dotnet/maui/media/logo.png" />

The

Image

Image Properties

The

Image

• Aspect: Controls how the image is scaled to fit its container. Common values include 
  AspectFit (scales image to fit while preserving aspect ratio) and 
  AspectFill (scales image to fill the entire container while preserving aspect ratio).

• HeightRequest and 
  WidthRequest: Specify explicit dimensions for the image.

• IsAnimationPlaying: Controls whether animated images (like GIFs) are playing.

• AutomationId: Useful for UI testing.

Controlling Aspect Ratio

Let's see how

AspectFit and 
AspectFill affect image display:

                

<Image Source="sample_image.jpg"
       Aspect="AspectFill"
       HeightRequest="200"
       WidthRequest="300" />

<Image Source="sample_image.jpg"
       Aspect="AspectFit"
       HeightRequest="200"
       WidthRequest="300" />
                

                
Handling Animation
                
For animated image formats like GIFs, you can control playback:
                

<Image Source="loading_animation.gif"
       IsAnimationPlaying="{Binding IsLoading}" />
                
            

Vector Graphics (SVG)

For scalable vector graphics, .NET MAUI leverages the SkiaSharp graphics library. You can display SVG files by using the

CommunityToolkit.Maui.Graphics package.

                
First, install the NuGet package:
                

dotnet add package CommunityToolkit.Maui.Graphics
                
                
Then, in your 
MauiProgram.cs, register the graphics services:

                

builder.UseMauiApp<App>().ConfigureFonts(fonts =>
{
    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
}).UseMauiCommunityToolkitGraphics(); // Add this line
                
                
You can then display SVGs using the 
GraphicsView control, often by defining a custom 
IGraphicsDrawable:

                

<GraphicsView x:Name="MyGraphicsView" />
                
                
And in code-behind:
                

public partial class MyPage : ContentPage
{
    public MyPage()
    {
        InitializeComponent();
        MyGraphicsView.Drawable = new SvgDrawable("Resources/Images/vector_icon.svg");
    }
}
                
                
The 
SvgDrawable class would handle parsing and drawing the SVG content.

            

Image Caching

When loading images from URIs, .NET MAUI provides automatic caching to improve performance. The cache is based on the URI. If you need to disable caching or manage it manually, you can explore more advanced options, but for most cases, the default caching is sufficient.

To clear the cache manually, you can use:

Microsoft.Maui.Controls.Image.ClearCache(new Uri(imageUrl));