Google Issue: https://issuetracker.google.com/issues/396827865
When using viewport-fit on Android WebView, the handling of safe area insets (env(safe-area-inset-*)) differs from iOS Safari (or iOS WebView). On iOS, the safe-area insets (e.g., safe-area-inset-top) are set to 0 unless viewport-fit=cover is explicitly used. On Android WebView, these insets are consistently set to non-zero values even if viewport-fit=contain or viewport-fit=auto is used. This mismatch leads to layout issues where Android WebView does not automatically avoid notches or rounded display cutouts, contrary to expectations and the behavior on iOS WKWebView.
For context, this issue came up in the Apache Cordova community while preparing the Cordova-Android release, which is updating its target SDK to 35 (Android 15), where edge-to-edge is enforced by default. We tested the manifest setting <item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>and this fixes it. We would like to properly support edge-to-edge in the future and therefore are looking for a solution for this.
There is a test page on https://niklas.merz.dev that lets you toggle between viewport-fit=containand viewport-fit=auto. It shows the value of --safe-area-top. Opening this page in a full screen WebView on Android or iOS shows the inconsistent behavior between both WebViews.
The code for the testing site is on GitHub.
Videos:
Android.webm
WKWebView.mp4
- Create a simple HTML test page that sets:
:root { --safe-area-top: env(safe-area-inset-top, 0px); --safe-area-right: env(safe-area-inset-right, 0px); --safe-area-bottom: env(safe-area-inset-bottom, 0px); --safe-area-left: env(safe-area-inset-left, 0px); }
- Use
<meta name="viewport" content="viewport-fit=contain">(orauto) in the<head>. - Display the values of these CSS variables in the DOM (e.g., via
getComputedStyle(document.documentElement).getPropertyValue("--safe-area-top")). - Compare results on:
- iOS Open test page in a full screen WKWebView
- Android Open test page in full screen WebView
- According to iOS behavior (and implied by W3C Round Display), when
viewport-fit=containorviewport-fit=auto, the browser should automatically avoid notches and effectively set safe-area insets to 0 (so developers don’t need to manually adjust layouts). - Only when
viewport-fit=covershould the safe-area insets be non-zero, allowing developers to opt in to drawing content under device cutouts.
- On Android WebView, safe-area insets report non-zero values even with
viewport-fit=containorviewport-fit=auto. Layouts that expect iOS-like handling (i.e., no manual inset calculations for contain/auto) end up incorrectly positioned under the notch/cutout.
- It breaks parity with iOS behavior and with developer expectations that
containorautoshould automatically avoid notches.- For WebView bases apps like Cordova this brings complications for cross-platform developers.
- Developers have to implement extra logic or conditional code for Android WebView to ensure content is properly padded or notched areas are avoided.
We found some issues that might be related:
- Google Issue 40699457 (for CSS env variables, though not precisely the same issue)
- Chromium Issue 394337118 (touches on
viewport-fitbut may not be specific to WebView) - W3C: CSS Round Display Level 1 (specification that describes
viewport-fit) - W3C env() CSS Draft Spec (work in progress)
- Align Android WebView behavior with iOS so that
viewport-fit=containandviewport-fit=autoignore cutouts (report safe-area insets as 0) unless developers explicitly opt in to usingviewport-fit=cover. - If changing the default behavior is not possible, provide clearer documentation or an explicit mechanism (similar to iOS) that distinguishes between ignoring vs. including cutouts.