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 

WindowSoftInputModeAdjust.Resize removed

If you used WindowSoftInputModeAdjust.Resize in .NET 9, replace it with SafeAreaEdges="All" on the ContentPage for equivalent keyboard avoidance.

Usage Patterns

Edge-to-edge immersive content

Set None on both page and layout — layouts default to Container:

Forms and critical content

Keyboard-aware chat layout

Mixed: edge-to-edge header + safe body + keyboard footer

Programmatic (C#)

var page = new ContentPage
{
    SafeAreaEdges = SafeAreaEdges.All
};

var grid = new Grid
{
    SafeAreaEdges = new SafeAreaEdges(
        left: SafeAreaRegions.Container,
        top: SafeAreaRegions.Container,
        right: SafeAreaRegions.Container,
        bottom: SafeAreaRegions.SoftInput)
};

Decision Framework

| Scenario | SafeAreaEdges value | |----------|---------------------| | Forms, critical inputs | All | | Photo viewer, video player, game | None (on page and layout) | | Scrollable content with fixed header/footer | Container | | Chat/messaging with bottom input bar | Per-edge: Container, Container, Container, SoftInput | | Blazor Hybrid app | None on page; CSS env() for insets |

Blazor Hybrid Integration

For Blazor Hybrid apps, let CSS handle safe areas to avoid double-padding.

1. Page stays edge-to-edge (default in .NET 10):

1. Add viewport-fit=cover in index.html:

1. Use CSS env() functions:

body {
    padding-top: env(safe-area-inset-top);
    padding-bottom: env(safe-area-inset-bottom);
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
}

Available CSS environment variables: env(safe-area-inset-top), env(safe-area-inset-bottom), env(safe-area-inset-left), env(safe-area-inset-right).

Migration from Legacy APIs

| Legacy (.NET 9 and earlier) | New (.NET 10+) | |-----------------------------|----------------| | ios:Page.UseSafeArea="True" | SafeAreaEdges="Container" | | Layout.IgnoreSafeArea="True" | SafeAreaEdges="None" | | WindowSoftInputModeAdjust.Resize | SafeAreaEdges="All" on ContentPage |

The legacy properties still compile but are marked obsolete. IgnoreSafeArea="True" maps internally to SafeAreaRegions.None.

Platform-Specific Behavior

iOS & Mac Catalyst

• Safe area insets cover: status bar, navigation bar, tab bar, notch/Dynamic Island, home indicator
• SoftInput includes the keyboard when visible
• Insets update automatically on rotation and UI visibility changes
• ScrollView with Default maps to UIScrollViewContentInsetAdjustmentBehavior.Automatic

Transparent navigation bar for content behind the nav bar:

Android

• Safe area insets cover: system bars (status/navigation) and display cutouts
• SoftInput includes the soft keyboard
• MAUI uses WindowInsetsCompat and WindowInsetsAnimationCompat internally
• Behavior varies by Android version and OEM edge-to-edge settings

Common Pitfalls

1. Forgetting to set None on the layout too. ContentPage SafeAreaEdges="None" makes the page edge-to-edge, but child layouts default to Container and still pad inward. Set None on both page and layout for truly immersive content.

1. Using SoftInput directly on ScrollView. ScrollView manages its own content insets and ignores SoftInput. Wrap the ScrollView in a Grid or StackLayout and apply SoftInput there.

1. Confusing Default with None. Default means "platform default for this control type" — on ScrollView (iOS) this enables automatic content insets. None means "no safe area padding at all."

1. Double-padding in Blazor Hybrid. Setting SafeAreaEdges="Container" on the page and using CSS env(safe-area-inset-*) results in doubled insets. Pick one approach — CSS is recommended for Blazor.

1. Missing viewport-fit=cover in Blazor. Without this meta tag, CSS env(safe-area-inset-*) values are always zero on iOS.

1. Assuming .NET 9 behavior on Android. After upgrading to .NET 10, Android ContentPage defaults to None (was effectively Container). Add SafeAreaEdges="Container" to restore the previous behavior.

1. Using legacy ios:Page.UseSafeArea in new code. The old API is iOS-only and obsolete. Always use SafeAreaEdges for cross-platform safe area management.

Checklist

• [ ] Android upgrade: SafeAreaEdges="Container" added if content goes under status bar
• [ ] Edge-to-edge: None set on both page and layout
• [ ] ScrollView keyboard avoidance uses wrapper Grid, not ScrollView's own SafeAreaEdges
• [ ] Blazor Hybrid: using either XAML or CSS safe areas, not both
• [ ] viewport-fit=cover in Blazor's index.html `` tag
• [ ] Legacy UseSafeArea / IgnoreSafeArea migrated to SafeAreaEdges

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dotnet
• Source: dotnet/skills
• License: MIT

Install and usage instructions live in the source repository linked above.