Maui App Icons Splash

.NET MAUI App Icons & Splash Screens

Common Pitfalls

❌ Android adaptive icon clipping

Android adaptive icons crop to a circular or squircle safe zone. If the foreground fills the canvas, it will be clipped.

<!-- ❌ Single-layer icon — foreground fills entire canvas, gets clipped -->
<MauiIcon Include="Resources\AppIcon\appicon.svg"
          Color="#512BD4" />

<!-- ✅ Composed icon with scaled foreground — stays in safe zone -->
<MauiIcon Include="Resources\AppIcon\appicon.svg"
          ForegroundFile="Resources\AppIcon\appiconfg.svg"
          ForegroundScale="0.65"
          Color="#512BD4" />

❌ Transparent splash screen Color

Some platforms ignore alpha in the splash Color and show black instead.

<!-- ❌ Transparent color — may render as black on some platforms -->
<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#00FFFFFF" />

<!-- ✅ Opaque color -->
<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#512BD4" />

❌ Confusing Color vs TintColor

• `Color` = background fill behind the icon/splash.
• `TintColor` = recolors the foreground image itself.

Setting only TintColor without visible foreground paths results in a blank icon.

⚠️ SVG rendering issues at build time

Complex SVGs with gradients, filters, or masks may not rasterize correctly via the Microsoft.Maui.Resizetizer MSBuild task.

<!-- Workaround: supply a pre-made PNG and skip resizing -->
<MauiIcon Include="Resources\AppIcon\appicon.png"
          Resize="false" />

⚠️ BaseSize mismatch

If your SVG viewBox doesn't match the desired logical size, set BaseSize explicitly — otherwise the output dimensions may be wrong.

<!-- SVG viewBox is 100x100 but you want 456x456 logical output -->
<MauiIcon Include="Resources\AppIcon\appicon.svg"
          BaseSize="456,456"
          Color="#512BD4" />

Best Practices

1. Use SVG whenever possible — one file, infinite scaling, smaller repo. 2. Set `BaseSize` explicitly when the SVG viewBox doesn't match the desired logical size. 3. Keep splash images simple — large or complex SVGs slow the build and may render with artifacts. 4. Test on real devices — emulator densities mask icon cropping, especially Android adaptive icon safe zones. 5. Use composed icons for Android — ForegroundFile + ForegroundScale="0.65" ensures the foreground stays within the safe zone.

Quick Troubleshooting

Checklist

• [ ] MauiIcon item exists in .csproj with Color set
• [ ] MauiSplashScreen item exists in .csproj with Color and BaseSize
• [ ] Android: using composed icon with ForegroundScale for safe zone compliance
• [ ] SVG sources are simple (no gradients/filters) or PNG fallback with Resize="false"
• [ ] Tested on a real device (not just emulator) for density and cropping

.NET MAUI App Icons & Splash Screens — API Reference

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:

  <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.