[Feature]: natively support and document safe area insets

[tafelnl]

Description

Now that all chromium bugs (including IME related ones) seem to be resolved around the safe area insets, we should have native support and documentation

Platforms

• iOS
• Android
• Web

Request or proposed solution

As per this update all safe area inset issues (including the ones related to the IME) should be resolved in the next version of chromium. We should have native support for this in Capacitor. I think it makes sense to include this in the core capacitor code without the developer needing to install a plugin or even passing any config values.

Possible solution: we should check for the chromium versions and then do the following logic:

• If webview lower than the one that has all issues fixed (probably 140) do something like what adjustMarginsForEdgeToEdge already does
• Otherwise, do nothing, and let the user handle the safe area insets
  • Even better would be to check for the viewport-fit=cover value and only then do nothing. This makes the behavior consistent across web, iOS and Android

Alternatives

No response

Additional Information

With this change the community can sunset all safe area/edge to edge related plugins. It would also close a lot of open issues.

We could also make this issue the overarching issues of all related ones, and close those already. A few related ones I found include:

#8095
#8055
#8103
#8093
#7951

Additionally, it would be great to add some (source of truth) documentation about the safe area insets, as this chromium bug has probably caused quite some confusion among developers

[timephy]

I've been struggling with correct SafeArea on Android for around a year now. I was happy to see "edge-to-edge" work properly after a recent update. This then caused #8095.

I would love to see progress in the direction of this issue 👍🏽

[theproducer]

Yeah, we are actively working on a solution for this. Expect to see some PRs related to this soon!

[croraf]

I'm thinking like, shouldn't all of that work out of the box after Chromium team fixes that issue (which is btw a critical issue, and regression, and I don't know why they don't patch it on Stable version...).

The Capacitor should just pass the current insets (including keyboard height as the fifth inset if the keyboard is docked to bottom) obtained with WindowInsets windowInsets = activity.getWindow().getDecorView().getRootWindowInsets(); (for Android) as browser env variables: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_environment_variables/Using_environment_variables#browser-defined_environment_variables

The challenge is perhaps only to handle the keyboard opening and closing animation.

I thought Capacitor already does this?

[tafelnl]

@croraf The passing of the safe insets should work out of the box indeed. But edge to edge mode still needs to be enabled properly on different Android versions. Moreover, for older webview versions (< 140) the chromium bug(s) still exists. So we need to account for those versions (similar to what adjustMarginsForEdgeToEdge currently already does would be fine I guess)

[Rossella-Mascia-Neosyn]

Hi, thanks for working on improving safe area handling in Capacitor.

I’ve been experiencing some safe area issues on iOS (content overlapping with the notch or bottom system bar). From what I understood, this proposal mostly focuses on Android / Chromium versions.

Do you know if there is already a recommended solution or upcoming change for iOS safe areas?
Should we rely only on viewport-fit=cover + CSS env(safe-area-inset-*), or is there something planned in Capacitor itself to handle this more consistently?

Any guidance would be greatly appreciated