Edit

Share via

Image

  • Article

The .NET Multi-platform App UI (.NET MAUI) Image displays an image that can be loaded from a local file, a URI, or a stream. The standard platform image formats are supported, including animated GIFs, and local Scalable Vector Graphics (SVG) files are also supported. For more information about adding images to a .NET MAUI app project, see Add images to a .NET MAUI app project.

Image defines the following properties:

  • Aspect, of type Aspect, defines the scaling mode of the image.
  • IsAnimationPlaying, of type bool, determines whether an animated GIF is playing or stopped. The default value of this property is false.
  • IsLoading, of type bool, indicates the loading status of the image. The default value of this property is false.
  • IsOpaque, of type bool, indicates whether the rendering engine may treat the image as opaque while rendering it. The default value of this property is false.
  • Source, of type ImageSource, specifies the source of the image.

These properties are backed by BindableProperty objects, which means that they can be styled, and be the target of data bindings.

Note

Font icons can be displayed by an Image by specifying the font icon data as a FontImageSource object. For more information, see Display font icons.

The ImageSource class defines the following methods that can be used to load an image from different sources:

  • FromFile returns a FileImageSource that reads an image from a local file.
  • FromUri returns an UriImageSource that downloads and reads an image from a specified URI.
  • FromStream returns a StreamImageSource that reads an image from a stream that supplies image data.

In XAML, images can be loaded from files and URIs by specifying the filename or URI as a string value for the Source property. Images can also be loaded from streams in XAML through custom markup extensions.

Important

Images will be displayed at their full resolution unless the size of the Image is constrained by its layout, or the HeightRequest or WidthRequest property of the Image is specified.

For information about adding app icons and a splash screen to your app, see App icons and Splash screen.

Load a local image

Images can be added to your app project by dragging them to the Resources\Images folder of your project, where its build action will automatically be set to MauiImage. At build time, vector images are resized to the correct resolutions for the target platform and device, and added to your app package. This is necessary because different platforms support different image resolutions, and the operating system chooses the appropriate image resolution at runtime based on the device's capabilities.

To comply with Android resource naming rules, all local image filenames must be lowercase, start and end with a letter character, and contain only alphanumeric characters or underscores. For more information, see App resources overview on developer.android.com.

Important

.NET MAUI converts SVG files to PNG files. Therefore, when adding an SVG file to your .NET MAUI app project, it should be referenced from XAML or C# with a .png extension.

Adhering to these rules for file naming and placement enables the following XAML to load and display an image:

<Image Source="dotnet_bot.png" />

The equivalent C# code is:

Image image = new Image
{
    Source = ImageSource.FromFile("dotnet_bot.png")
};

The ImageSource.FromFile method requires a string argument, and returns a new FileImageSource object that reads the image from the file. There's also an implicit conversion operator that enables the filename to be specified as a string argument to the Image.Source property:

Image image = new Image { Source = "dotnet_bot.png" };

Load a remote image

Remote images can be downloaded and displayed by specifying a URI as the value of the Source property:

<Image Source="https://aka.ms/campus.jpg" />

The equivalent C# code is:

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

The ImageSource.FromUri method requires a Uri argument, and returns a new UriImageSource object that reads the image from the Uri. There's also an implicit conversion for string-based URIs:

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

Image caching

Caching of downloaded images is enabled by default, with cached images being stored for 1 day. This behavior can be changed by setting properties of the UriImageSource class.

The UriImageSource class defines the following properties:

  • Uri, of type Uri, represents the URI of the image to be downloaded for display.
  • CacheValidity, of type TimeSpan, specifies how long the image will be stored locally for. The default value of this property is 1 day.
  • CachingEnabled, of type bool, defines whether image caching is enabled. The default value of this property is true.

These properties are backed by BindableProperty objects, which means that they can be styled, and be the target of data bindings.

To set a specific cache period, set the Source property to an UriImageSource object that sets its CacheValidity property:

<Image>
    <Image.Source>
        <UriImageSource Uri="https://aka.ms/campus.jpg"
                        CacheValidity="10:00:00:00" />
    </Image.Source>
</Image>

The equivalent C# code is:

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CacheValidity = new TimeSpan(10,0,0,0)
};

In this example, the caching period is set to 10 days.

Load an image from a stream

Images can be loaded from streams with the ImageSource.FromStream method:

Image image = new Image
{
    Source = ImageSource.FromStream(() => stream)
};

Important

Image caching is disabled on Android when loading an image from a stream with the ImageSource.FromStream method. This is due to the lack of data from which to create a reasonable cache key.

Load a font icon

The FontImage markup extension enables you to display a font icon in any view that can display an ImageSource. It provides the same functionality as the FontImageSource class, but with a more concise representation.

The FontImage markup extension is supported by the FontImageExtension class, which defines the following properties:

  • FontFamily of type string, the font family to which the font icon belongs.
  • Glyph of type string, the unicode character value of the font icon.
  • Color of type Color, the color to be used when displaying the font icon.
  • Size of type double, the size, in device-independent units, of the rendered font icon. The default value is 30. In addition, this property can be set to a named font size.

Note

The XAML parser allows the FontImageExtension class to be abbreviated as FontImage.

The Glyph property is the content property of FontImageExtension. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the Glyph= part of the expression provided that it's the first argument.

The following XAML example shows how to use the FontImage markup extension:

<Image BackgroundColor="#D1D1D1"
       Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

In this example, the abbreviated version of the FontImageExtension class name is used to display an XBox icon, from the Ionicons font family, in an Image:

Screenshot of the FontImage markup extension.

While the unicode character for the icon is \uf30c, it has to be escaped in XAML and so becomes &#xf30c;.

For information about displaying font icons by specifying the font icon data in a FontImageSource object, see Display font icons.

Load animated GIFs

.NET MAUI includes support for displaying small, animated GIFs. This is accomplished by setting the Source property to an animated GIF file:

<Image Source="demo.gif" />

Important

While the animated GIF support in .NET MAUI includes the ability to download files, it does not support caching or streaming animated GIFs.

By default, when an animated GIF is loaded it will not be played. This is because the IsAnimationPlaying property, that controls whether an animated GIF is playing or stopped, has a default value of false. Therefore, when an animated GIF is loaded it will not be played until the IsAnimationPlaying property is set to true. Playback can be stopped by reseting the IsAnimationPlaying property to false. Note that this property has no effect when displaying a non-GIF image source.

Control image scaling

The Aspect property determines how the image will be scaled to fit the display area, and should be set to one of the members of the Aspect enumeration:

  • AspectFit - letterboxes the image (if required) so that the entire image fits into the display area, with blank space added to the top/bottom or sides depending on whether the image is wide or tall.
  • AspectFill - clips the image so that it fills the display area while preserving the aspect ratio.
  • Fill - stretches the image to completely and exactly fill the display area. This may result in the image being distorted.
  • Center - centers the image in the display area while preserving the aspect ratio.