/maui-safe-area

name: maui-safe-area
description: >-
  .NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers the
  new SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard
  avoidance, Blazor Hybrid CSS safe areas, migration from legacy iOS-only APIs,
  and platform-specific behavior for Android, iOS, and Mac Catalyst.
  USE FOR: "safe area", "edge-to-edge", "SafeAreaEdges", "SafeAreaRegions",
  "keyboard avoidance", "notch insets", "status bar overlap", "iOS safe area",
  "Android edge-to-edge", "content behind status bar", "UseSafeArea migration",
  "soft input keyboard", "IgnoreSafeArea replacement".
  DO NOT USE FOR: general layout or grid design (use Grid and StackLayout),
  app lifecycle handling (use maui-app-lifecycle), theming or styling
  (use maui-theming), or Shell navigation structure.
license: MIT

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

| Control | Default | Notes | |---------|---------|-------| | `ContentPage` | `None` | Edge-to-edge. **Breaking change from .NET 9 on Android.** | | `Layout` (Grid, StackLayout, etc.) | `Container` | Respects bars/notch, flows under keyboard | | `ScrollView` | `Default` | iOS maps to automatic content insets. Only `Container` and `None` take effect. | | `ContentView` | `None` | Inherits parent behavior | | `Border` | `None` | Inherits parent behavior |

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" />