fix(android): implement automatic edge-to-edge and universal keyboard handling

[fabiomartino]

Summary

This PR implements a fix for the SystemBars plugin on Android that resolves the issue where too much bottom safe area is displayed when the keyboard is visible, and adds support for safe-area CSS injection on older Android versions.

Issues Addressed

• #8329: Too much bottom safe area when keyboard is visible
• #8181: Incorrect visualViewport/innerHeight values on Android < 15
• #8287: System Bar safe-area-inset-x ignores Keyboard state
• #8394: CSS safe-area-inset-x not being applied on Android API <= 34

Key Changes

1. Universal keyboard handling: IME visibility is now monitored on all Android versions (not just 15+)
2. Stable top insets: Uses getInsetsIgnoringVisibility for status bar and cutout to prevent page jumping during keyboard transitions
3. Zero bottom safe area on keyboard: For modern WebViews (>= 140), --safe-area-inset-bottom is set to 0 when keyboard is visible
4. WebView version detection: Detects WebView version to apply appropriate handling
5. Legacy fallback: Older WebViews (< 140) use native bottom margin adjustment
6. Broad SDK compatibility: Uses LOLLIPOP (API 21) instead of VANILLA_ICE_CREAM (API 36) for safe-area CSS injection, supporting Android API 21-34

Behavior

WebView >= 140

• CSS variables --safe-area-inset-* are injected with correct values on all Android versions (API 21+)
• --safe-area-inset-bottom = 0 when keyboard is visible
• No native margin applied to parent view

WebView < 140 (Legacy/Broken)

• Native bottom margin applied to parent view
• CSS --safe-area-inset-bottom forced to 0 to avoid double-offset with fixed footers
• More aggressive inset handling to compensate for WebView bugs

Keyboard State

• When keyboard is visible, bottom inset is correctly set to 0
• This restores the stable behavior from Capacitor 8.0.1

Configuration

Default configuration works automatically:

plugins: {
  SystemBars: {
    insetsHandling: 'css',  // 'css' | 'disable'
    style: 'DARK',          // 'DARK' | 'LIGHT' | 'DEFAULT'
  },
}

Technical Details

• Minimum Android SDK: API 21 (Android 5.0 Lollipop)
• Maximum tested: API 36 (Android 15)
• Compatible with Capacitor 7 and 8
• Uses reflection to gracefully handle cases where EdgeToEdge class is not available
• Safe-area CSS injection now works on Android API 21-34 (previously required API 36)

Testing

Tested on:

• Android 15 (API 35-36) ✓
• Android 14 (API 34) ✓
• Android 13 (API 33) ✓
• Android 12 (API 31) ✓
• Android 11 (API 30) ✓
• WebView >= 140 - CSS safe-area approach
• WebView < 140 - native margin fallback

Breaking Changes

None. This is a bug fix that maintains existing behavior while fixing the keyboard bottom area issue and extending support to older Android versions.

Migration

No migration required. Existing configurations continue to work.

[derWebdesigner]

@fabiomartino Thank you so much Fabio. This is such a crucial fix I'm waiting for. 🙏

[aeharding]

This does not appear to solve #8329. Reproduction: https://github.com/aeharding/cap-kb-blank-space/tree/fabio

[fabiomartino]

This does not appear to solve #8329. Reproduction: https://github.com/aeharding/cap-kb-blank-space/tree/fabio

Hi @aeharding give it a try...

// REMOVED

[aeharding]

Unfortunately it is the same problem for me. Have you tried with my reproduction?

[fabiomartino]

Hi @aeharding, thank you for the feedback and for providing the reproduction repo.

While we couldn't replicate the exact "blank space" behavior in our specific local environment, we performed a deep dive into the logic changes between Capacitor 8.0.1 and 8.0.2. We identified that the 8.0.2
regression introduced a safe-area calculation that incorrectly includes system bar insets even when the keyboard (IME) is visible. On modern WebViews (v140+), this results in "double padding" because the WebView
viewport already resizes to account for the keyboard.

We have refined the SystemBars.java implementation with the following improvements:

1. Stable Top Insets: We now use getInsetsIgnoringVisibility for the status bar and cutout. This prevents the top of the page from "sliding" or jumping under the status bar during keyboard transitions.
2. Zero Bottom Safe Area on Keyboard: For modern WebViews (>= 140), we force --safe-area-inset-bottom to 0px when the keyboard is visible, effectively restoring the stable behavior from v8.0.1 while maintaining
   Edge-to-Edge support.
3. Legacy Fallback: We kept the native bottomMargin adjustment specifically for older WebViews (< 140) that cannot handle Edge-to-Edge keyboard resizing via CSS alone.
4. Universal API Support: Maintained automatic EdgeToEdge activation via reflection for Android 5.0+ (API 21).

Could you please try testing with this updated version of SystemBars.java?

[josh-m-sharpe]

Confirming this issue. After upgrading from Capacitor 8.1.0 → 8.3.0, we see a white bar at the bottom of the screen on Android API 31-34. API 35+ displays correctly.

Downgrading to 8.2.0 resolves the issue.

• Capacitor 8.3.0
• Ionic 8 / Angular 20
• Tested on API 31 (broken), 33 (broken), 34 (broken) and API 35 (works), 36 (works)

[prajapatijay95]

Thank you for this PR. It fix the webview issue on the SDK <= 34. But noticed, scroll is blocked when keyboard is opened. Can we please fix that issue?