Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Every app has a logo icon that represents it, and that icon typically appears in multiple places. For example, on iOS the app icon appears on the Home screen and throughout the system, such as in Settings, notifications, and search results, and in the App Store. On Android, the app icon appears as a launcher icon and throughout the system, such as on the action bar, notifications, and in the Google Play Store. On Windows, the app icon appears in the app list in the start menu, the taskbar, the app's tile, and in the Microsoft Store.
In a .NET Multi-platform App UI (.NET MAUI) app project, an app icon can be specified in a single location in your app project. At build time, this icon can be automatically resized to the correct resolution for the target platform and device, and added to your app package. This avoids having to manually duplicate and name the app icon on a per platform basis. By default, bitmap (non-vector) image formats aren't automatically resized by .NET MAUI.
A .NET MAUI app icon can use any of the standard platform image formats, including Scalable Vector Graphics (SVG) files.
Important
.NET MAUI converts SVG files to Portable Network Graphic (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. The only reference to the SVG file should be in your project file.
Change the icon
In your .NET MAUI project, the image with the MauiIcon build action designates the icon to use for your app. This is represented in your project file as the <MauiIcon> item. For image-based icons, such as SVG or PNG files, only the first <MauiIcon> item is processed. Any subsequent image-based <MauiIcon> items are ignored.
Important
An Apple Icon Composer .icon bundle must be the only <MauiIcon> item for its iOS or Mac Catalyst target. Combining it with another icon produces a build error, rather than selecting the first icon. For more information, see Use an Apple Icon Composer bundle.
The icon defined by your app can be composed of a single image, by specifying the file as the Include attribute:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.svg" />
</ItemGroup>
To use a different image file as the icon, replace the existing <MauiIcon> item. If you add the new image by dragging it to the Resources\AppIcon folder of your project, Visual Studio will automatically set its build action to MauiIcon and will create a corresponding <MauiIcon> item in your project file.
Note
An app icon can also be added to other folders of your app project. However, in this scenario its build action must be manually set to MauiIcon in the Properties window.
To comply with Android resource naming rules, app icon 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.
After changing the icon file, you might need to clean the project in Visual Studio, rebuild it, and deploy it again. To clean the project, right-click on the project file in the Solution Explorer pane, and select Clean.
Caution
Uninstalling an app deletes its locally stored data. Don't uninstall or reset an app as a routine step to refresh its icon.
After changing the icon, review the Platform specific configuration information.
Composed icon
Alternatively, the app icon can be composed of two images, one image representing the background and another representing the foreground. Since icons are transformed into PNG files, the composed app icon will be first layered with the background image, typically an image of a pattern or solid color, followed by the foreground image. In this case, the Include attribute represents the icon background image, and the Foreground attribute represents the foreground image:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" />
</ItemGroup>
On Android, a ForegroundScale attribute can be optionally specified to rescale the foreground image so that it fits on the app icon. For more information, see Adaptive launcher.
Important
The background image (Include attribute) must be specified for the <MauiIcon> item. The foreground image (ForegroundFile attribute) is optional.
Use an Apple Icon Composer bundle
Starting in .NET 11 RC 2, you can use an Apple Icon Composer .icon bundle as a MauiIcon on iOS and Mac Catalyst. The Apple asset compiler (actool) compiles the bundle into the app's asset catalog. .NET MAUI doesn't rasterize the bundle through Resizetizer. Existing SVG and PNG icon processing is unchanged.
This feature requires the .NET Apple workload version 26.5.11720-net11-p6 or later. The .NET 11 RC 2 Apple workload version is 27.0.12211-net11-rc.2. Use the Xcode version required by your Apple workload.
Save the complete bundle in your project, for example at Resources\AppIcon\appicon.icon. A .icon bundle is a directory, not a single image file. Keep its root icon.json file and its Assets directory, including nested asset folders:
Resources/
AppIcon/
appicon.icon/
icon.json
Assets/
background.png
foreground.png
Reference the bundle directory in the Include attribute, not icon.json or an individual asset. .NET MAUI includes the bundle's files recursively. Configure layers, colors, and effects in Icon Composer. The image resizing, tinting, and composition settings in this article apply to image-based icons, not native .icon bundles.
Replace the existing <MauiIcon> item with mutually exclusive conditions. Select the .icon bundle for iOS and Mac Catalyst, and keep an SVG or PNG fallback for other platforms:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.icon"
Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios' Or $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'" />
<MauiIcon Include="Resources\AppIcon\appicon.svg"
ForegroundFile="Resources\AppIcon\appiconfg.svg"
Color="#512BD4"
Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'ios' And $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'maccatalyst'" />
</ItemGroup>
Each Apple target must select exactly one icon. Don't keep an unconditional SVG or PNG <MauiIcon> item alongside the .icon item. An Android or Windows target must use an image-based icon, not the .icon bundle.
The build derives the AppIcon property from the bundle directory name without the .icon extension. In this example, the name is appicon. You don't need to set AppIcon yourself. If you already set it, remove the property or make its value match the bundle name. The build uses this name instead of the template's legacy XSAppIconAssets selection, without changing your Info.plist file.
After you save changes in Icon Composer, build the project again. .NET MAUI tracks additions, deletions, renames, and content changes to files inside the bundle, including nested folders, for incremental asset compilation.
Resolve bundle validation errors
The build reports errors for the following conditions:
| Condition | Action |
|---|---|
The Apple workload doesn't support .icon bundles. |
Use Apple workload 26.5.11720-net11-p6 or later. |
| The bundle directory doesn't exist. | Correct the MauiIcon path and include the complete bundle in your project. |
The bundle has no root icon.json file. |
Save or copy the complete bundle from Icon Composer. |
The Assets directory has no asset files. |
Include the assets referenced by icon.json. A .DS_Store file doesn't count as an asset. |
More than one .icon bundle is selected. |
Select only one bundle for each iOS or Mac Catalyst target. |
A .icon bundle and another MauiIcon are selected for the same Apple target. |
Remove the additional icon item or correct its platform condition. |
An explicit AppIcon value doesn't match the bundle name. |
Remove AppIcon or set it to the bundle directory name without the extension. |
Set the base size
.NET MAUI uses your icon across multiple platforms and devices, and attempts to resize the icon according to each platform and device. The app icon is also used for different purposes, such as a store entry for your app or the icon used to represent the app after it's installed on a device.
The base size of your icon represents baseline density of the image, and is effectively the 1.0 scale factor that all other sizes are derived from. If you don't specify the base size for a bitmap-based app icon, such as a PNG file, the image isn't resized. If you don't specify the base size for a vector-based app icon, such as an SVG file, the dimensions specified in the image are used as the base size. To stop a vector image from being resized, set the Resize attribute to false.
The following figure illustrates how base size affects an image:
The process shown in the previous figure follows these steps:
- A: The image is added as the .NET MAUI icon and has dimensions of 210x260, and the base size is set to 424x520.
- B: .NET MAUI automatically scales the image to match the base size of 424x520.
- C: As different target platforms require different sizes of the image, .NET MAUI automatically scales the image from the base size to different sizes.
Tip
Use an SVG image as your icon. SVG images can upscale to larger sizes and still look crisp and clean. Bitmap-based images, such as a PNG or JPG image, look blurry when upscaled.
The base size is specified with the BaseSize="W,H" attribute, where W is the width of the icon and H is the height of the icon. The following example sets the base size:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.png" BaseSize="128,128" />
</ItemGroup>
And the following example stops the automatic resizing of a vector-based image:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.svg" Resize="false" />
</ItemGroup>
Recolor the background
If the background image used in composing the app icon uses transparency, it can be recolored by specifying the Color attribute on the <MauiIcon>. The following example sets the background color of the app icon to red:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.svg" Color="#FF0000" />
</ItemGroup>
Color values can be specified in hexadecimal, using the format: #RRGGBB or #AARRGGBB. The value of RR represents the red channel, GG the green channel, BB the blue channel, and AA the alpha channel. Instead of a hexadecimal value, you may use a named .NET MAUI color, such as Red or PaleVioletRed.
Caution
If you don't define a background color for your app icon the background is considered to be transparent on iOS and Mac Catalyst. This will cause an error during App Store Connect verification and you won't be able to upload your app.
Recolor the foreground
If the app icon is composed of a background (Include) image and a foreground (ForegroundFile) image, the foreground image can be tinted. To tint the foreground image, specify a color with the TintColor attribute. The following example tints the foreground image yellow:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>
Color values can be specified in hexadecimal, using the format: #RRGGBB or #AARRGGBB. The value of RR represents the red channel, GG the green channel, BB the blue channel, and AA the alpha channel. Instead of a hexadecimal value, you may use a named .NET MAUI color, such as Red or PaleVioletRed.
Use a different icon per platform
For image-based icons, such as SVG or PNG files, you can use different resources or settings per platform. Add the Condition attribute to the <MauiIcon> item, and query for the specific platform. If the condition is met, the <MauiIcon> item is processed. Only the first valid image-based <MauiIcon> item is used by .NET MAUI, so all conditional items should be declared first, followed by a default <MauiIcon> item without a condition. The following XML demonstrates declaring a specific icon for Windows and a fallback icon for all other platforms:
Important
The unconditional fallback in the following example is for image-based icons only. If you use a native .icon bundle, make the Apple and non-Apple conditions mutually exclusive, as shown in Use an Apple Icon Composer bundle.
<ItemGroup>
<!-- App icon for Windows -->
<MauiIcon Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'"
Include="Resources\AppIcon\backicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="#40FF00FF" />
<!-- App icon for all other platforms -->
<MauiIcon Include="Resources\AppIcon\appicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>
You can set the target platform by changing the value compared in the condition to one of the following values:
'ios''maccatalyst''android''windows'
For example, a condition that targets Android would be Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'".
Platform-specific configuration
While the project file declares which resources the app icon is composed from, you're still required to update the individual platform configurations with reference to those app icons. The following information describes these platform-specific settings.
The icon Android uses is specified in the Android manifest, which is located at Platforms\Android\AndroidManifest.xml. The manifest/application node contains two attributes to define the icon: android:icon and android:roundIcon. The values of these two attributes follow this format: @mipmap/{name} and @mipmap/{name}_round, respectively. The value for {name} is derived from the .NET MAUI project file's <MauiIcon> item, specifically the file name defined by the Include attribute, without its path or extension.
Consider the following example, which defines the resource Resources\AppIcon\healthapp.png as the icon:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\healthapp.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>
The transformed name, the resource without the path or extension, is healthapp. The values for android:icon and android:roundIcon would be @mipmap/healthapp and @mipmap/healthapp_round, respectively. The android manifest should be updated to match healthapp as the icon:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application android:allowBackup="true" android:icon="@mipmap/healthapp" android:roundIcon="@mipmap/healthapp_round" android:supportsRtl="true"></application>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
Tip
Instead of creating new image files for the icon, simply replace the two image files provided by the .NET MAUI template: Resources\AppIcon\appicon.svg for the background and Resources\AppIcon\appiconfg.svg for the foreground.
Adaptive launcher
.NET MAUI supports creating an adaptive launcher icon on Android 8.0 and higher, from the app icon. Adaptive launcher icons can display as various shapes across different device models, including circular and square. For more information about adaptive icons, see the Android developer guide: Adaptive icons.
Adaptive launcher icons are composed icons, using a background layer and a foreground layer, and an optional scaling value. For more information, see the Composed icon section. If the composed icon is defined, by specifying the ForegroundFile attribute, an adaptive launcher icon will be generated. The following XML demonstrates defining an icon that is used as an adaptive launcher icon:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" ForegroundScale="0.65" Color="#512BD4" />
</ItemGroup>
The ForegroundScale attribute can be optionally specified to rescale the foreground image so that it fits on the app icon. It's a percentage value so 0.65 will be translated as 65%.
Themed icon monochrome layer
On Android 13 and higher, the system can render a themed app icon that uses a single monochrome glyph tinted with colors derived from the user's wallpaper. By default, .NET MAUI uses the ForegroundFile image as the monochrome layer. To use a different glyph for the themed icon, specify the MonochromeFile attribute on the <MauiIcon> item:
<ItemGroup>
<MauiIcon Include="Resources\AppIcon\appicon.svg"
ForegroundFile="Resources\AppIcon\appiconfg.svg"
MonochromeFile="Resources\AppIcon\appiconmono.svg"
ForegroundScale="0.65"
Color="#512BD4" />
</ItemGroup>
The MonochromeFile image should be a single-color glyph designed to read clearly when tinted by the system. The image is included in the generated adaptive icon as the <monochrome> layer of the adaptive-icon drawable. If MonochromeFile isn't specified, the foreground image continues to be used as the monochrome source.
For more information about themed icons on Android, see Adaptive icons and Support themed app icons on developer.android.com.
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
