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)
}

SoftInput and Container are combinable flags: SafeAreaRegions.Container | SafeAreaRegions.SoftInput = respect system bars and keyboard.

SafeAreaEdges Struct

public readonly struct SafeAreaEdges
{
    public SafeAreaRegions Left { get; }
    public SafeAreaRegions Top { get; }
    public SafeAreaRegions Right { get; }
    public SafeAreaRegions Bottom { get; }

    // Uniform — same value for all four edges
    public SafeAreaEdges(SafeAreaRegions uniformValue)

    // Horizontal / Vertical
    public SafeAreaEdges(SafeAreaRegions horizontal, SafeAreaRegions vertical)

    // Per-edge
    public SafeAreaEdges(SafeAreaRegions left, SafeAreaRegions top,
                         SafeAreaRegions right, SafeAreaRegions bottom)
}

Static presets: SafeAreaEdges.None, SafeAreaEdges.All, SafeAreaEdges.Default.

XAML Type Converter

Follows Thickness-like comma-separated syntax:

<!-- Uniform -->
SafeAreaEdges="Container"

<!-- Horizontal, Vertical -->
SafeAreaEdges="Container, SoftInput"

<!-- Left, Top, Right, Bottom -->
SafeAreaEdges="Container, Container, Container, SoftInput"

Control Defaults

Breaking Changes from .NET 9

ContentPage default changed to None

In .NET 9, Android ContentPage behaved like Container. In .NET 10, the default is None on all platforms. If your Android content goes behind the status bar after upgrading:

<!-- .NET 10 default — content extends under status bar -->
<ContentPage>

<!-- Restore .NET 9 Android behavior -->
<ContentPage SafeAreaEdges="Container">

WindowSoftInputModeAdjust.Resize superseded

WindowSoftInputModeAdjust.Resize still exists and still compiles (it is not removed and not obsolete), but it is Android-only. For cross-platform keyboard avoidance prefer SafeAreaEdges="All" (or the SoftInput region) on the ContentPage.

Usage Patterns

Edge-to-edge immersive content

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

<ContentPage SafeAreaEdges="None">
    <Grid SafeAreaEdges="None">
        <Image Source="background.jpg" Aspect="AspectFill" />
        <VerticalStackLayout Padding="20" VerticalOptions="End">
            <Label Text="Overlay text" TextColor="White" FontSize="24" />
        </VerticalStackLayout>
    </Grid>
</ContentPage>

Forms and critical content

<ContentPage SafeAreaEdges="All">
    <VerticalStackLayout Padding="20">
        <Label Text="Safe content" FontSize="18" />
        <Entry Placeholder="Enter text" />
        <Button Text="Submit" />
    </VerticalStackLayout>
</ContentPage>

Keyboard-aware chat layout

<ContentPage>
    <Grid RowDefinitions="*,Auto"
          SafeAreaEdges="Container, Container, Container, SoftInput">
        <ScrollView Grid.Row="0">
            <VerticalStackLayout Padding="20" Spacing="10">
                <Label Text="Messages" FontSize="24" />
            </VerticalStackLayout>
        </ScrollView>
        <Border Grid.Row="1" BackgroundColor="LightGray" Padding="20">
            <Grid ColumnDefinitions="*,Auto" Spacing="10">
                <Entry Placeholder="Type a message..." />
                <Button Grid.Column="1" Text="Send" />
            </Grid>
        </Border>
    </Grid>
</ContentPage>

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

<ContentPage SafeAreaEdges="None">
    <Grid RowDefinitions="Auto,*,Auto">
        <Grid BackgroundColor="{StaticResource Primary}">
            <Label Text="App Header" TextColor="White" Margin="20,40,20,20" />
        </Grid>
        <ScrollView Grid.Row="1" SafeAreaEdges="Container">
            <!-- Use Container, not All — ScrollView only honors Container and None -->
            <VerticalStackLayout Padding="20">
                <Label Text="Main content" />
            </VerticalStackLayout>
        </ScrollView>
        <Grid Grid.Row="2" SafeAreaEdges="SoftInput"
              BackgroundColor="LightGray" Padding="20">
            <Entry Placeholder="Type a message..." />
        </Grid>
    </Grid>
</ContentPage>

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

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):

<ContentPage SafeAreaEdges="None">
    <BlazorWebView HostPage="wwwroot/index.html">
        <BlazorWebView.RootComponents>
            <RootComponent Selector="#app" ComponentType="{x:Type local:Routes}" />
        </BlazorWebView.RootComponents>
    </BlazorWebView>
</ContentPage>

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