[Bug]: CSS safe-area-inset-x, is not being applied on Android mobiles with API <= 34

[Marius-Romanus]

Capacitor Version

https://capacitorjs.com/docs/apis/system-bars#android-note

The CSS is not being applied on Android mobiles with API <= 34.

In an SDK 36 build.

I have tested it on API versions 29, 34, 35 and 36. All tests were performed with the webview updated to the latest version.

If there is an API limitation preventing the safe-area-inset-x from being implemented, it is not mentioned in the documentation.

It is configured in the config file and in the global CSS.

const config: CapacitorConfig = {
...
  plugins: {
    SystemBars: {
      insetsHandling: 'css'
    }
  }
};

html {
    --ion-safe-area-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
    --ion-safe-area-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
    --ion-safe-area-left: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
    --ion-safe-area-right: var(--safe-area-inset-right, env(safe-area-inset-right, 0px));
}

---

In an emulator with Android API 35 and 36, it injects correctly:

The problem lies in the difficulty of maintaining a consistent strategy with API 36 and the global setting insetsHandling: 'css'.

This is because the safe area is injected into some models but not others, so you can't apply edge-to-edge handling in any API without resorting to StatusBar.setOverlaysWebView({ overlay: true }); in older versions.

I've seen this pull request, which I'm not sure if it resolves these issues:
#8384

Other API Details

node --version
v24.14.0

npm --version
11.11.1

Platforms Affected

• iOS
• Android
• Web

Current Behavior

CSS is not injected in versions lower than API 34

Expected Behavior

CSS is injected in earlier versions. If this isn't possible, please indicate it in the documentation at https://capacitorjs.com/docs/apis/system-bars

Project Reproduction

https://github.com/Marius-Romanus/demo-safe-area

Additional Information

The project I'm sharing is a simple fresh installation of Ionic and Capacitor, since the CSS is displayed directly in the HTML.

[fabiomartino]

@Marius-Romanus Can you test PR #8366? It addresses the API <= 34 issue by lowering the minimum SDK version from VANILLA_ICE_CREAM (API 36) to LOLLIPOP (API 21) for safe-area CSS injection.

[Marius-Romanus]

Hi!

I'll tell you about the tests I've done with your PR. I only have one physical phone to test with; the rest is through emulation.

Physical Xioami mi 8 API 29, KO The footer is missing.

element.style {
    --safe-area-inset-top: 32px;
    --safe-area-inset-right: 0px;
    --safe-area-inset-bottom: 0px;
    --safe-area-inset-left: 0px;
}

Emulation Pixel 9 API 36, OK

 {
    --safe-area-inset-top: 54px;
    --safe-area-inset-right: 0px;
    --safe-area-inset-bottom: 48px;
    --safe-area-inset-left: 0px;
}

Emulation Pixel 9 API 35, OK

 {
    --safe-area-inset-top: 54px;
    --safe-area-inset-right: 0px;
    --safe-area-inset-bottom: 24px;
    --safe-area-inset-left: 0px;
}

Emulation Pixel 7a API 34, OK

{
    --safe-area-inset-top: 44px;
    --safe-area-inset-right: 0px;
    --safe-area-inset-bottom: 48px;
    --safe-area-inset-left: 0px;
}

Emulation Pixel 4 API 29, KO The footer is missing.

 {
    --safe-area-inset-top: 30px;
    --safe-area-inset-right: 0px;
    --safe-area-inset-bottom: 0px;
    --safe-area-inset-left: 0px;
}

[fabiomartino]

ok... not to bad... after all... I will apply few changes and update soon...
Thx to test it out!

[fabiomartino]

@Marius-Romanus We've updated PR #8366 with a new fix specifically for the legacy WebView (< 140) case on older Android devices.

Key changes:

• API ≤ 30: Forces CSS safe-area vars to 0 in legacy fallback path to avoid double compensation in footer/tab-bar layouts
• API 30-33: Preserves original IME margins behavior
• API ≥ 34: Uses modern CSS injection (no changes)
• Overall: Now injects --safe-area-inset-* CSS variables on all Android versions (API 21+)

Please test PR #8366 again

Test on:

• API 29 (Pixel 4 EMU) - keyboard closed and open
• API 30 (Pixel 5 EMU) - keyboard closed and open
• API 34 (samsung SM-A137F REAL) - keyboard closed and open
• API 36 (Pixel 9 Pro XL EMU) - keyboard closed and open

Let us know if the footer is now properly positioned without excessive spacing on API 29!

[Marius-Romanus]

Hi, I've tried the new version, and it seems everything is still the same; the bottom part is missing in both the physical and emulator versions of API 29.

Just in case it helps to compare your Pixel 4 emulator with mine, I usually update Google Play Services, Chrome, WebView, and everything related within the emulator itself.

Edit: I also have the build SDK at version 36, AGP version 9.1.0, and Gradle 9.4.1; basically, everything is up to date.

[fabiomartino]

Hi @Marius-Romanus, could you please run one last test with the latest changes?
And thank you — your API 29 + modern WebView edge case was exactly what I had missed.

[Marius-Romanus]

Hi, I wanted to let you know that APIs 36, 35, and 34 work fine in the emulator.

API 29 doesn't work correctly in either the emulator or the physical device; all the pixels appear as 0.

element.style {
    --safe-area-inset-top: 0px;
    --safe-area-inset-right: 0px;
    --safe-area-inset-bottom: 0px;
    --safe-area-inset-left: 0px;
}

[fabiomartino]

Hi @Marius-Romanus — to avoid pushing PR updates too frequently, could you please run one local fine-tuning pass by editing only applyInsets() in SystemBars.java?

From my local replication/tuning:

• API 29 (Pixel 4), WebView not updated:
  • --safe-area-inset-top: 30px
  • --safe-area-inset-right: 0px
  • --safe-area-inset-bottom: 48px
  • --safe-area-inset-left: 0px
• API 29 (Pixel 4), WebView updated:
  • --safe-area-inset-top: 30px
  • --safe-area-inset-right: 0px
  • --safe-area-inset-bottom: 48px
  • --safe-area-inset-left: 0px
• Visual result in my emulator:
  • Footer is aligned with the Android system buttons (looks correct)

I replaced this section with:

        if (isApiLowerThan30 && hasBrokenWebViewVersion && hasViewportCover && v.hasWindowFocus() && v.isShown()) {
            setViewMargins(v, Insets.NONE);
            int bottomInset = keyboardVisible ? 0 : stableInsets.bottom;
            injectSafeAreaCSSWithBottom(stableInsets.top, stableInsets.right, bottomInset, stableInsets.left);
            return WindowInsetsCompat.CONSUMED;
        }

        if (isApiLowerThan30 && hasModernWebView && hasViewportCover) {
            resetViewBottomMargin(v);
            int bottomInset = keyboardVisible ? 0 : stableInsets.bottom;
            injectSafeAreaCSSWithBottom(stableInsets.top, stableInsets.right, bottomInset, stableInsets.left);
            return insets;
        }

Please test this matrix and report both CSS values and visual result:

API	WebView	Keyboard Closed	Keyboard Open
29	old/new	CSS vars + UI	CSS vars + UI
30	old/new	CSS vars + UI	CSS vars + UI
34	current	CSS vars + UI	CSS vars + UI

What to check:

• No inflated top/bottom bars
• Footer is not hidden behind system buttons
• No jump/glitch when opening or closing the keyboard
• --safe-area-inset-bottom becomes 0 when the keyboard is visible

You should only need to tune:

1. branch conditions (API/WebView)
2. values passed to injectSafeAreaCSSWithBottom(...)
   (Only touch margins if keyboard behavior still needs adjustment.)
   Thanks again — your API 29 + modern WebView edge case was very helpful.

private WindowInsetsCompat applyInsets(View v, WindowInsetsCompat insets) {
    int webViewVersion = getWebViewMajorVersion();
    boolean hasBrokenWebViewVersion = webViewVersion < WEBVIEW_VERSION_WITH_SAFE_AREA_FIX;
    boolean hasModernWebView = !hasBrokenWebViewVersion;
    boolean isApiLowerThan30 = Build.VERSION.SDK_INT < Build.VERSION_CODES.R;
    boolean keyboardVisible = insets.isVisible(WindowInsetsCompat.Type.ime());
    Insets stableInsets = insets.getInsetsIgnoringVisibility(
        WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout());
    Insets currentInsets = insets.getInsets(
        WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout());
    /*
     * TUNE POINT #1 (API < 30 + WebView < 140):
     * If old devices still show double compensation, use zero CSS + CONSUMED.
     * If they need semantic CSS values, use stableInsets values instead.
     */
    if (isApiLowerThan30 && hasBrokenWebViewVersion && hasViewportCover && v.hasWindowFocus() && v.isShown()) {
        setViewMargins(v, Insets.NONE);
        // Option A (anti-double-compensation):
        // injectSafeAreaCSSWithBottom(0, 0, 0, 0);
        // Option B (semantic values):
        int bottomInset = keyboardVisible ? 0 : stableInsets.bottom;
        injectSafeAreaCSSWithBottom(stableInsets.top, stableInsets.right, bottomInset, stableInsets.left);
        return WindowInsetsCompat.CONSUMED;
    }
    /*
     * TUNE POINT #2 (API < 30 + WebView >= 140):
     * Usually semantic mode: stableInsets.
     * If top/bottom are inflated, try forcing zeros temporarily.
     */
    if (isApiLowerThan30 && hasModernWebView && hasViewportCover) {
        resetViewBottomMargin(v);
        // Option A (semantic values):
        int bottomInset = keyboardVisible ? 0 : stableInsets.bottom;
        injectSafeAreaCSSWithBottom(stableInsets.top, stableInsets.right, bottomInset, stableInsets.left);
        // Option B (strict neutral CSS):
        // injectSafeAreaCSSWithBottom(0, 0, 0, 0);
        return insets;
    }
    /*
     * Modern/default path (API >= 30)
     */
    if (hasViewportCover) {
        int topInset = stableInsets.top;
        int bottomInset = keyboardVisible ? 0 : currentInsets.bottom;
        injectSafeAreaCSSWithBottom(topInset, currentInsets.right, bottomInset, currentInsets.left);
    }
    /*
     * Legacy WebView fallback for remaining cases.
     * Usually keep as-is unless keyboard behavior is broken.
     */
    if (hasBrokenWebViewVersion && hasViewportCover && v.hasWindowFocus() && v.isShown()) {
        if (keyboardVisible) {
            Insets imeInsets = insets.getInsets(WindowInsetsCompat.Type.ime());
            // TUNE POINT #3 (keyboard-only):
            // If keyboard causes excessive shift, test Insets.NONE.
            setViewMargins(v, Insets.of(0, 0, 0, imeInsets.bottom));
        } else {
            setViewMargins(v, Insets.NONE);
        }
        return WindowInsetsCompat.CONSUMED;
    }
    resetViewBottomMargin(v);
    // Chromium keyboard workaround (WebView < 144)
    if (hasViewportCover && webViewVersion < WEBVIEW_VERSION_WITH_SAFE_AREA_KEYBOARD_FIX && keyboardVisible) {
        return new WindowInsetsCompat.Builder(insets)
            .setInsets(
                WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout(),
                Insets.of(currentInsets.left, currentInsets.top, currentInsets.right, 0)
            )
            .build();
    }
    return insets;
}

[Marius-Romanus]

I've quickly tested it on both the emulator and the physical machine with API 29, and it seems to be working fine 🙌. If you need it, I can test the other emulators tomorrow.

One question I have for you: should you really be changing the bottom part? Or should the programmer know whether the keyboard is open or not and act accordingly?

[fabiomartino]

RE: safe-area-inset-bottom and keyboard behavior

Your question is valid and touches on an important design decision.

Why we set safe-area-inset-bottom = 0 when keyboard is visible:
safe-area-inset-* represents the space reserved for system bars (navigation bar, gesture area) — not the keyboard. When the keyboard is open:

1. The keyboard already provides visual separation between content and input
2. Setting bottom = 0 avoids "double offset" in footer/tab-bar layouts (no double padding)
3. It prevents jump/glitch artifacts when keyboard appears/disappearsThe pragmatic approach:
   On Android, there is no native CSS variable (keyboard-inset) to expose keyboard state to web content. Without this, we can't give developers the choice to handle it themselves.
   The iOS comparison:
   iOS keeps env(safe-area-inset-bottom) constant even with keyboard open, but iOS apps typically don't use edge-to-edge + keyboard overlays the same way Android does. The two platforms have different constraints.

---

Question for you:

With the latest change (setting bottom = 0 when keyboard visible), has your issue been finally resolved? Please test:

• API 29 (physical + emulator)
• API 30, 34, 35, 36

And let us know:

• Footer is not hidden behind system buttons
• No jump/glitch when keyboard appears
• No excessive padding when keyboard is open

[Marius-Romanus]

I was testing it on the physical device, and a system message popped up (asking me if I wanted to enable GPS). When I returned, the edge-to-edge functionality disappeared. This also happens when I put the app in the background and then return. I tried using the original Java code, and this doesn't happen there.