The Hidden Bug in .NET MAUI Android Layouts (and How to Fix It Cleanly)

📱 Fixing Layout Overlap in .NET MAUI on Android API 35+: A Developer’s Guide

Have you ever opened your beautiful .NET MAUI app on a modern Android device, only to find your layout sneaking under the status bar or navigation bar?

---

Join our exclusive WhatsApp group for Xamarin and .NET MAUI developers to connect with experts, share insights, and get help with your projects. Whether you're a beginner or an experienced developer, this group is the perfect place to enhance your skills and collaborate with the community.

---

This is a common frustration—especially when targeting Android 15 (API 35), where edge-to-edge layouts and gesture navigation are the new normal.

In this post, we’ll walk through the root cause and a clean, production-grade solution using custom layout handling and AndroidX window insets—all without disrupting your cross-platform codebase.

---

🚨 The Problem: UI Elements Overlapping System Bars

Starting from Android 10 (API 29), Google began promoting edge-to-edge UI for a more immersive experience. With Android 11 (API 30) and later, this became the standard.

But in Android 15+ (API 35), this behavior is enforced by default. That means:

• Your layouts may extend behind the status bar at the top.
• Important content like buttons or fields may appear under the navigation bar.
• The system no longer adds padding automatically—you have to handle it.

---

🎯 The Solution

To fix this, we’ll:

1. Intercept layout rendering on Android using LayoutHandler.
2. Listen for window insets (safe screen areas).
3. Apply margins dynamically to avoid overlap.
4. Ensure it only affects Android API 35+ to stay safe on older versions.

---

🛠️ Step-by-Step Implementation

🧷 Step 1: Modify CreateMauiApp in MauiProgram.cs

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    try
    {
        builder
            .UseMauiApp<App>();

#if ANDROID
        Microsoft.Maui.Handlers.LayoutHandler.Mapper.AppendToMapping("ApplyInsets", (handler, view) =>
        {
            if ((int)Android.OS.Build.VERSION.SdkInt >= 35)
            {
                if (handler.PlatformView is Android.Views.View nativeView)
                {
                    AndroidX.Core.View.ViewCompat.SetOnApplyWindowInsetsListener(nativeView,
                        new Platforms.Android.InsetsListener((insets) =>
                        {
                            var sysBars = insets.GetInsets(AndroidX.Core.View.WindowInsetsCompat.Type.SystemBars());

                            Microsoft.Maui.ApplicationModel.MainThread.BeginInvokeOnMainThread(() =>
                            {
                                if (view is Layout layout)
                                {
                                    layout.Margin = new Thickness(
                                        sysBars.Left,
                                        35,
                                        sysBars.Right,
                                        35
                                    );
                                }
                            });

                            return AndroidX.Core.View.WindowInsetsCompat.Consumed;
                        }));
                }
            }
        });
#endif
    }
    catch (Exception ex)
    {
        // Optional logging
    }

#if DEBUG
    builder.Logging.AddDebug();
#endif

    return builder.Build();
}

---

🧱 Step 2: Add InsetsListener Class in Platforms/Android

using Android.Views;
using AndroidX.Core.View;
using Java.Lang;

namespace YourAppNamespace.Platforms.Android
{       
    public class InsetsListener : Java.Lang.Object, IOnApplyWindowInsetsListener
    {
        private readonly Func<WindowInsetsCompat, WindowInsetsCompat> _onApply;

        public InsetsListener(Func<WindowInsetsCompat, WindowInsetsCompat> onApply)
        {
            _onApply = onApply;
        }

        public WindowInsetsCompat OnApplyWindowInsets(global::Android.Views.View v, WindowInsetsCompat insets)
        {
            return _onApply(insets);
        }
    }
}

---

🔍 Code Breakdown

Component	Purpose
LayoutHandler.Mapper.AppendToMapping	Hooks into MAUI layout system to apply Android-specific behavior.
SetOnApplyWindowInsetsListener	Attaches listener to capture system bar sizes (status/nav).
GetInsets(Type.SystemBars())	Gets safe insets to avoid system overlap.
layout.Margin	Applies margin to layout based on safe zone.
InsetsListener	Bridges Android insets with .NET MAUI layout.

---

Table of Contents for .Net Maui

• What is .NET MAUI and why it’s important
• Applying the MVVM pattern for cleaner architecture
• Working with Renderers and Mappers
• Storing data locally using SQLite and Preferences
• Image Picker from gallery
• Sending push notifications using Firebase
• Publishing your app to Android and iOS stores
• 🌟 Explore More Topics

---

📱 Why API 35+

From API 34 onward, Android fully defaults to immersive edge-to-edge UI, and the system expects developers to manually handle insets. That’s why we conditionally apply this only on:

if ((int)Android.OS.Build.VERSION.SdkInt >= 35)

---

👨‍💻 Real-World Scenarios

• Login or splash screens
• Layouts using VerticalStackLayout, Grid, or ContentPage
• Apps targeting Android 14/15

---

🧪 Pro Tip: Use Actual Insets Instead of Hardcoding

Use this if you want pixel-perfect spacing:

layout.Margin = new Thickness(
    sysBars.Left,
    sysBars.Top,
    sysBars.Right,
    sysBars.Bottom
);

---

💡 Bonus: Limit to Specific Layouts

You can use attached properties or wrap layouts in a SafeLayout view if you want to control which screens are affected.

---

🛑 Common Mistakes to Avoid

• ❌ Don’t hardcode fixed margins on every layout
• ❌ Don’t rely on SafeAreaInsets on Android — they work better on iOS
• ❌ Don’t ignore gesture navigation bars

---

✅ Final Recap

Step	Description
1	Modify MauiProgram.cs to intercept layout
2	Add InsetsListener.cs to apply margins
3	Use window insets for dynamic spacing
4	Test on Android 14+ real devices

---

🚀 Result

With this in place, your MAUI layouts will:

• Respect the system UI bars
• Look clean and uncluttered
• Work seamlessly on Android 14 and 15+

---

🏷️ Hashtags and Tags

#dotnetmaui, #androiddev, #layoutfix, #androidapi35, #mauiandroid, #mauitips, #systembarinsets, #crossplatform, #mobileux, #appdevelopment