OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add dotnet/skills --skill maui-safe-area
.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.
npx skills add dotnet/skills --skill maui-safe-area
.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.UseSafeAreaandLayout.IgnoreSafeAreaproperties instead.
ios:Page.UseSafeArea, Layout.IgnoreSafeArea, or WindowSoftInputModeAdjust.Resizeenv(safe-area-inset-*) coordinationnet10.0-* or later for the new APIsSoftInput and Container are combinable flags:
SafeAreaRegions.Container | SafeAreaRegions.SoftInput = respect system bars and keyboard.
Static presets: SafeAreaEdges.None, SafeAreaEdges.All, SafeAreaEdges.Default.
Follows Thickness-like comma-separated syntax:
| 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 |
NoneIn .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:
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.
Set None on both page and layout — layouts default to Container:
| 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 |
For Blazor Hybrid apps, let CSS handle safe areas to avoid double-padding.
viewport-fit=cover in index.html:env() functions:Available CSS environment variables: env(safe-area-inset-top), env(safe-area-inset-bottom), env(safe-area-inset-left), env(safe-area-inset-right).
| 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 ios:Page.UseSafeArea and Layout.IgnoreSafeArea properties still compile but are marked obsolete. IgnoreSafeArea="True" maps internally to SafeAreaRegions.None. WindowSoftInputModeAdjust.Resize is not obsolete — it remains supported, but is Android-only.
SoftInput includes the keyboard when visibleScrollView with Default maps to UIScrollViewContentInsetAdjustmentBehavior.AutomaticTransparent navigation bar for content behind the nav bar:
SoftInput includes the soft keyboardWindowInsetsCompat and WindowInsetsAnimationCompat internallyForgetting 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.
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.
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."
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.
Missing viewport-fit=cover in Blazor. Without this meta tag, CSS env(safe-area-inset-*) values are always zero on iOS.
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.
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.
SafeAreaEdges="Container" added if content goes under status barNone set on both page and layoutSafeAreaEdgesviewport-fit=cover in Blazor's index.html <meta viewport> tagUseSafeArea / IgnoreSafeArea migrated to SafeAreaEdgespublic 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)
}<!-- Uniform -->
SafeAreaEdges="Container"
<!-- Horizontal, Vertical -->
SafeAreaEdges="Container, SoftInput"
<!-- Left, Top, Right, Bottom -->
SafeAreaEdges="Container, Container, Container, SoftInput"<!-- .NET 10 default — content extends under status bar -->
<ContentPage>
<!-- Restore .NET 9 Android behavior -->
<ContentPage SafeAreaEdges="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><ContentPage SafeAreaEdges="All">
<VerticalStackLayout Padding="20">
<Label Text="Safe content" FontSize="18" />
<Entry Placeholder="Enter text" />
<Button Text="Submit" />
</VerticalStackLayout>
</ContentPage><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><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>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)
};<ContentPage SafeAreaEdges="None">
<BlazorWebView HostPage="wwwroot/index.html">
<BlazorWebView.RootComponents>
<RootComponent Selector="#app" ComponentType="{x:Type local:Routes}" />
</BlazorWebView.RootComponents>
</BlazorWebView>
</ContentPage><meta name="viewport" content="width=device-width, initial-scale=1.0,
maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />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);
}<!-- .NET 9 (legacy, iOS-only) -->
<ContentPage xmlns:ios="clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls"
ios:Page.UseSafeArea="True">
<!-- .NET 10+ (cross-platform) -->
<ContentPage SafeAreaEdges="Container"><Shell Shell.BackgroundColor="#80000000" Shell.NavBarHasShadow="False" />