Maui Safe Area

Safe Area — Gotchas & Best Practices (.NET 10+)

Breaking Changes

⚠️ .NET 9 → 10: ContentPage default changed to None

ContentPage now defaults to edge-to-edge (None) on all platforms. In .NET 9, Android ContentPage behaved like Container. If your Android content goes under the status bar after upgrading, add SafeAreaEdges="Container" explicitly.

⚠️ WindowSoftInputModeAdjust.Resize migration

If you used WindowSoftInputModeAdjust.Resize in .NET 9, you may need SafeAreaEdges="All" on the ContentPage to maintain keyboard avoidance.

Common Gotchas

1. Layouts default to Container, not None

For true edge-to-edge, set SafeAreaEdges="None" on both the page and layouts:

2. SoftInput on ScrollView has no effect

ScrollView manages its own content insets. Wrap it in a Grid/StackLayout instead:

     ... 

3. Default is not None

Default = "use platform defaults for this control type." None = "edge-to-edge." They differ significantly on ScrollView (iOS maps Default to automatic content insets).

4. Blazor Hybrid double-padding

5. iOS Shell/NavigationPage edge-to-edge

Content won't extend behind the nav bar unless you set a transparent background AND hide the separator:

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 |

Migration Quick Reference

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

Legacy properties still work but are obsolete.

Best Practices

1. Combine SafeAreaEdges with Padding — safe area handles insets, Padding adds visual spacing:

```xaml

```

1. Use per-control settings for mixed layouts (edge-to-edge header + safe body + keyboard-aware footer).

1. For Blazor Hybrid, prefer CSS env() and leave SafeAreaEdges="None".

Add viewport-fit=cover to the `` tag.

1. Test on notched devices (iPhone X+, Android cutouts), tablets in landscape, and varying screen sizes.

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: davidortinau
• Source: davidortinau/maui-skills
• License: MIT

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