Assets and image display

Uno Platform automatically processes assets from your app's project and makes them available on all platforms.

Support for automatically generating assets in multiple resolutions from SVG or PNG is also provided using Uno.Resizetizer.

Platform-specific assets such as BundleResource and AndroidAssets are also supported on the heads, when required.

Supported asset types

The following image file types are supported as Content assets:

	`.bmp` (Win BMP)	`.gif`	`.heic` (Apple)	`.jpg` & `.jpeg` (JFIF)	`.png`	`.webp`	`.pdf`	`.svg`
WinUI	✔️	✔️	❌	✔️	✔️	✔️	❌	✔️
Uno Platform targets¹	✔️	✔️²	❌³	✔️	✔️	✔️²	❌	✔️⁴
Android native renderer (6.x)¹	❌⁵	✔️⁶	❌⁵	✔️	✔️	❌⁵	❌	✔️⁴
iOS/tvOS native renderer (6.x)¹	✔️	✔️⁶	✔️	✔️	✔️	✔️⁶	❌	✔️⁴
WebAssembly native renderer (6.x)¹	✔️	✔️²	❌³	✔️	✔️	✔️²	❌³	✔️

This row covers every Uno Platform target except the Windows App SDK head, which uses WinUI (the row above). In Uno Platform 6.x, Android, iOS/tvOS and WebAssembly use this shared rendering when UnoFeatures includes SkiaRenderer (the default for new projects), and the native renderers otherwise. An app built without SkiaSharp, for example one using only the WebGPU renderer, decodes images with a managed decoder instead. It doesn't load animated WebP, lossy WebP with transparency, or BMP other than uncompressed 8, 24 and 32-bit.
Animated images always play. BitmapImage.AutoPlay, IsPlaying, Play() and Stop() are not implemented.
Depends on the browser on WebAssembly. For example, Safari decodes .heic and Chrome doesn't.
Uno Platform 6.x needs the Svg Uno feature. See Using SVG images.
Doesn't load as an ms-appx:/// asset, because the native Android renderer only packages .png, .jpg, .jpeg and .gif files as images. It loads from a stream or a web URL.
Animated images show only the first frame.

Adding an asset to your project

This is just like adding an asset to a WinUI project.

Add an image file to the Assets directory of the solution's app project.
Select the item and set the build action to Content, if not already set.

Referencing an asset

Use assets added to your project with the ms-appx:/// scheme.

See the examples below for XAML:

<!-- Relative path without a leading '/' uses assets from the library where the XAML is located -->
<Image Source="Assets/MyImage.png" />
<!-- Explicitly qualify the asset, when used from multiple project libraries -->
<Image Source="ms-appx:///[MyApp]/Assets/MyImage.png" />

Note

For single project solutions, the [MyApp] qualifier is not required when explicitly qualifying the asset.

<Image Source="ms-appx:///Assets/MyImage.png" />

<Image Source="ms-appx:///Assets/Images/MyImage.png" />

For Uno's latest project template where images are saved in the Images folder.

Referencing an asset from code

You can also reference assets from code using the ms-appx:/// scheme. For example:

<Image x:Name="MyImage" />

// from XAML code behind
MyImage.Source = "ms-appx:///Assets/MyImage.png";

or using bindings:

// from a ViewModel
public string ImagePath { get; set ;} = "ms-appx:///Assets/MyImage.png";

<Image Source="{x:Bind ImagePath}" />

You can also get assets directly using StorageFile.GetFileFromApplicationUriAsync.

Qualify an asset

When developing Windows apps, developers can load different assets at runtime based on attributes that qualify their visibility in the app's UX. This allows you to tailor your app to different contexts to better suit users' hardware or language preferences.

For instance, such qualifiers can selectively load different assets depending on scale, language, theme preferences, etc. This feature is notably useful when supporting high DPI screens or the norms of differing regions.

Note

To become more familiar with qualifiers, check out Microsoft's documentation for a conceptual overview of the feature: Microsoft: Tailor your resources for language, scale, high contrast, and other qualifiers

Uno Platform allows you to use the same feature on multiple platforms. However, only a subset of those qualifiers currently have support.

Table of scales

Not all scales are supported on all platforms:

Scale	WinUI	iOS/tvOS	Android
`100`	scale-100	@1x	mdpi
`125`	scale-125	N/A	N/A
`150`	scale-150	N/A	hdpi
`200`	scale-200	@2x	xhdpi
`300`	scale-300	@3x	xxhdpi
`400`	scale-400	N/A	xxxhdpi

We recommend including assets for each of these scales: 100, 150, 200, 300, and 400. Only compatible scales will be included in each platform.

Note

In the Android head project (via the csproj), you can set the UseHighDPIResources property to False in debug. In those cases, only assets with scale 100 (mdpi) and scale 150 (hdpi) will be included. This reduces deployment time when debugging as fewer assets are processed and transferred to the device or simulator.

Examples

\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

\Assets\Images\scale-100\logo.png
\Assets\Images\scale-200\logo.png
\Assets\Images\scale-400\logo.png

Language

Use it as you would on WinUI/UWP, but keep in mind that some language or region combinations might not work on all platforms.

The following languages have been verified to work on all platforms:

-en -en-US -en-CA -fr -fr-FR -fr-CA -es

Examples

\Assets\Images\en\logo.png
\Assets\Images\fr\logo.png
\Assets\Images\es\logo.png

\Assets\Images\logo.language-en.png
\Assets\Images\logo.language-fr.png
\Assets\Images\logo.language-es.png

Dark theme support

Tip

Supported on Android only

A theme qualifier can be specified for the image loader to use an asset based on the current app theme.

Examples

/Assets/theme-light/ThemeTestImage.png
/Assets/theme-dark/ThemeTestImage.png

Custom (platform)

Sometimes, you might want to use a different asset depending on the platform. Because there is no platform qualifier on WinUI, Uno Platform provides the custom qualifier. It is only interpreted on Android and iOS/tvOS heads — on WinUI, desktop, and WebAssembly heads nothing reads it, so every custom-* variant is copied and none is selected.

Platform	Qualifier value
iOS	`ios`
tvOS	`ios` (tvOS shares iOS's resource converter)
Android	`android`

Uno.UI's RetargetAssets task interprets these values on iOS/tvOS and Android heads and excludes the variants that do not match the current platform.

Examples

\Assets\Images\custom-ios\logo.png
\Assets\Images\custom-android\logo.png

\Assets\Images\logo.custom-ios.png
\Assets\Images\logo.custom-android.png