Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-safe-area

@79bb4bf
Run it yourself

.NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard avoidance, Blazor Hybrid CSS safe areas, migration from legacy 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". DO NOT USE FOR: general layout or grid design (use maui-collectionview), app lifecycle handling (use maui-app-lifecycle), or theming (use maui-theming).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-safe-area

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈164 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈2.1k more on demand in 1 file.

Description uses 8.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈656 characters, or 8.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

<!-- ❌ .NET 10 default — content goes under status bar on Android -->
<ContentPage>

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

⚠️ 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:

<!-- ❌ Grid still respects system bars (its default is Container) -->
<ContentPage SafeAreaEdges="None">
    <Grid>
        <Image Source="bg.jpg" Aspect="AspectFill" />
    </Grid>
</ContentPage>

<!-- ✅ Both page and layout set to None -->
<ContentPage SafeAreaEdges="None">
    <Grid SafeAreaEdges="None">
        <Image Source="bg.jpg" Aspect="AspectFill" />
    </Grid>
</ContentPage>

2. SoftInput on ScrollView has no effect

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

<!-- ❌ SoftInput is ignored on ScrollView -->
<ScrollView SafeAreaEdges="SoftInput">

<!-- ✅ Set SoftInput on the wrapper layout -->
<Grid SafeAreaEdges="Container, Container, Container, SoftInput">
    <ScrollView> ... </ScrollView>
</Grid>

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

<!-- ❌ XAML safe area + CSS env() = double padding -->
<ContentPage SafeAreaEdges="Container">
    <BlazorWebView ... />  <!-- CSS also uses env(safe-area-inset-*) -->

<!-- ✅ Pick ONE approach — CSS is recommended for Blazor -->
<ContentPage SafeAreaEdges="None">
    <BlazorWebView ... />  <!-- CSS handles all insets with env() -->

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:

<Shell Shell.BackgroundColor="#80000000"
       Shell.NavBarHasShadow="False" />

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:

    <ContentPage SafeAreaEdges="All">
        <VerticalStackLayout Padding="20">
            <!-- Both applied — no conflict -->
        </VerticalStackLayout>
    </ContentPage>
  2. Use per-control settings for mixed layouts (edge-to-edge header + safe body + keyboard-aware footer).

  3. For Blazor Hybrid, prefer CSS env() and leave SafeAreaEdges="None". Add viewport-fit=cover to the <meta viewport> tag.

  4. 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 <meta viewport> tag
  • Legacy UseSafeArea / IgnoreSafeArea migrated to SafeAreaEdges

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides technical guidance and code examples for managing safe area layouts in .NET MAUI applications. No security issues were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-safe-area