.NET MAUI App Icons & Splash Screens

Use this skill when configuring app icons, splash screens, or troubleshooting image asset issues in .NET MAUI projects.

App Icons

Single-source icon

Add one MauiIcon item in the .csproj; the build resizes it for every platform:

<MauiIcon Include="Resources\AppIcon\appicon.svg"
          Color="#512BD4" />

• •Source: SVG (recommended) or PNG. SVGs are converted to platform PNGs at build.
• •Color: Background fill behind the icon (hex or named color).
• •BaseSize: Logical size before platform scaling (default 456,456 for icons).
• •TintColor: Recolors the foreground of a single-layer icon.

Composed / layered icons

Use Include (background) + ForegroundFile (foreground) for a two-layer icon:

<MauiIcon Include="Resources\AppIcon\appicon.svg"
          ForegroundFile="Resources\AppIcon\appiconfg.svg"
          ForegroundScale="0.65"
          Color="#512BD4" />

• •ForegroundFile: SVG/PNG overlaid on the background.
• •ForegroundScale: Scale factor for the foreground layer (0.0–1.0).
• •Composed icons automatically produce Android adaptive icons (API 26+).

Platform-specific references

Sizing guidelines

• •Provide the largest resolution you need; the tooling scales down.
• •For SVG sources, BaseSize controls the logical canvas size.
• •Android generates mdpi through xxxhdpi variants automatically.
• •iOS generates all required @1x, @2x, @3x sizes.

Splash Screens

Basic splash screen

Add one MauiSplashScreen item in the .csproj:

<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#512BD4"
                  BaseSize="128,128" />

• •Color: Background color of the splash screen.
• •BaseSize: Logical size of the splash image (default 128,128).
• •TintColor: Recolors the splash image foreground.

Platform behavior

Android (12+)

• •The splash icon is centered on a colored background.
• •Uses @style/Maui.SplashTheme set in AndroidManifest.xml:
  xml

  <activity android:theme="@style/Maui.SplashTheme" ... />
  

• •Pre-Android 12 uses the same theme with a legacy splash.

iOS / Mac Catalyst

• •Build generates MauiSplash.storyboard in the app bundle.
• •Referenced automatically in Info.plist (UILaunchStoryboardName).

Windows

• •The splash image is embedded in the app package; no extra config needed.

SVG to PNG conversion

• •All SVG sources (MauiIcon, MauiSplashScreen, MauiImage) are rasterized to PNGs at build time by the Microsoft.Maui.Resizetizer MSBuild task.
• •Conversion respects BaseSize, TintColor, and Color properties.
• •To skip resizing for a pre-made PNG, set Resize="false".
• •If an SVG renders incorrectly, simplify paths or supply a PNG instead.

Image sizing best practices

1. •Use SVG whenever possible — one file, infinite scaling, smaller repo.
2. •Set BaseSize explicitly when your SVG viewBox doesn't match the desired logical size.
3. •Keep splash images simple — large or complex SVGs slow build and may render with artifacts.
4. •Test on real devices — emulator densities can mask icon cropping, especially Android adaptive icon safe zones.
5. •Avoid transparency in splash Color — some platforms ignore alpha and show black instead.

Quick troubleshooting