maui-safe-area

Safe Area & Edge-to-Edge Layout (.NET 10+)

.NET 10 introduces a brand-new, cross-platform safe area API that replaces the legacy iOS-only UseSafeArea and the layout-level IgnoreSafeArea properties. The new SafeAreaEdges property and SafeAreaRegions flags enum give you per-edge, per-control safe area management on Android, iOS, and Mac Catalyst from a single API surface.

This is new API surface in .NET 10. If the project targets .NET 9 or earlier, these APIs do not exist. Guide the developer to the legacy ios:Page.UseSafeArea and Layout.IgnoreSafeArea properties instead.

When to Use

• Content overlaps status bar, notch, Dynamic Island, or home indicator after upgrading to .NET 10
• Implementing edge-to-edge / immersive layouts (photo viewers, video players, maps)
• Keyboard avoidance for chat or form UIs
• Migrating from ios:Page.UseSafeArea, Layout.IgnoreSafeArea, or WindowSoftInputModeAdjust.Resize
• Blazor Hybrid apps that need CSS env(safe-area-inset-*) coordination
• Mixed layouts with an edge-to-edge header but a safe-area-respecting body

When Not to Use

• Projects targeting .NET 9 or earlier — use the legacy iOS-specific APIs
• General page layout questions unrelated to system bars or keyboard — use standard layout guidance
• App lifecycle or navigation structure — use maui-app-lifecycle or Shell guidance
• Theming or visual styling — use the maui-theming skill

Inputs

• Target framework: must be net10.0-* or later for the new APIs
• Target platforms: Android, iOS, Mac Catalyst (Windows does not have system bar insets)
• UI approach: XAML/C#, Blazor Hybrid, or MauiReactor

SafeAreaRegions Enum

[Flags]
public enum SafeAreaRegions
{
    None      = 0,       // Edge-to-edge — no safe area padding
    SoftInput = 1 << 0,  // Pad to avoid the on-screen keyboard
    Container = 1 << 1,  // Stay inside status bar, notch, home indicator
    Default   = -1,      // Use the platform default for the control type
    All       = 1 << 15  // Respect all safe area insets (most restrictive)
}