feat(android): add adjustMarginsForEdgeToEdge configuration option

[markemer]

No description provided.

[dpogue]

Just a note that the windowOptOutEdgeToEdgeEnforcement option is removed in Android 16 (as per https://android-developers.googleblog.com/2025/02/second-beta-android16.html)

Edge to edge opt-out going away

Android 15 enforced edge-to-edge for apps targeting Android 15 (SDK 35), but your app could opt-out by setting R.attr#windowOptOutEdgeToEdgeEnforcement to true. Once your app targets Android 16 (Baklava), R.attr#windowOptOutEdgeToEdgeEnforcement is deprecated and disabled and your app cannot opt-out of going edge-to-edge. To be compatible with Android 16 Beta 2, ensure your app supports edge-to-edge and remove any use of R.attr#windowOptOutEdgeToEdgeEnforcement. To support edge-to-edge, see the Compose and Views guidance. Please let us know about concerns in our tracker on the feedback page.

[markemer]

@dpogue and other interested parties:

Just a note that the windowOptOutEdgeToEdgeEnforcement option is removed in Android 16 (as per https://android-developers.googleblog.com/2025/02/second-beta-android16.html)

Capacitor 8 will for sure deal with that directly, however, setting adjustMarginsForEdgeToEdge to 'force' will force the margin adjustment - if you opt into Edge to Edge yourself, that would be the best option as well.

[markemer]

Added two minor comments.

But I think setting the default to auto in a minor release is still a breaking change as it will change the original behavior of Capacitor 7.0.0 apps, which while it might not have been the desired behavior for some users, other that might have adjusted the bottom inset by using CSS already.

I'm with you there - seems that we're gonna have to fix a group of people no matter what. Either the people that are currently broken, or the people that fixed it with some hacky-ness. I'm of two minds. I feel weird not default fixing a bug because people might have fixed it a weird other way, but I also feel weird breaking people who thought they were fixed. I think we might want to use disable for 7 just because it is a behavior change, but I don't love it.

[dpogue]

Is there anything here that will break if the WebView does start handling safe-area-insets properly? My guess is that because this is using LinearLayout margins outside the WebView it'll be fine, but wanted to ask

[luisbytes]

Added two minor comments.
But I think setting the default to auto in a minor release is still a breaking change as it will change the original behavior of Capacitor 7.0.0 apps, which while it might not have been the desired behavior for some users, other that might have adjusted the bottom inset by using CSS already.

I'm with you there - seems that we're gonna have to fix a group of people no matter what. Either the people that are currently broken, or the people that fixed it with some hacky-ness. I'm of two minds. I feel weird not default fixing a bug because people might have fixed it a weird other way, but I also feel weird breaking people who thought they were fixed. I think we might want to use disable for 7 just because it is a behavior change, but I don't love it.

I completely agree with you, that error should not have appeared with capacitor v7, it is an unexpected behavior.

In a project I managed to solve it with CSS using a third-party plugin but I did not release it to the public. I'm still waiting for the fix from the ionic team to update a month after the stable release of v7, this error is still present.

[jcesarmobile]

Is there anything here that will break if the WebView does start handling safe-area-insets properly? My guess is that because this is using LinearLayout margins outside the WebView it'll be fine, but wanted to ask

If the WebView handled the safe-area-insets properly (or users are using a plugin that provides those values to do a similar approach themselves), users could avoid the safe areas using css but still style the safe areas from css, meaning that if they have the header and tab bar with a color, they could also have the safe areas with the same color, styled from css.

With the current implementation where the whole WebView avoids the safe areas, the safe areas are white as there are not views in that area.
So an app with dark mode and the fix looks like this

While it used to look like this:

Of course in the last one the tab bar is partially hidden because safe-area-inset-bottom doesn't work on Android at the moment, so that's why some users are using plugins that provide the value of the safe areas to avoid them themselves.
And if they are doing that already and we make the auto the default value, they will have to set the value to disabled to get their previous behavior as they most likely don't want the white areas and I consider that a breaking change.

EDIT:
Looks like the safe areas are not always white, they seem to change the color if you start the app in dark mode, but not if you change to dark mode while using the app, so it's slightly less ugly, but you can still notice the different colors on the status bar and navigation bar areas.

[dpogue]

Of course in the last one the tab bar is partially hidden because safe-area-inset-bottom doesn't work on Android at the moment, so that's why some users are using plugins that provide the value of the safe areas to avoid them themselves.

yeah... I'm asking because I'm trying to get this fixed in Android WebView, and there are concerns about breaking apps that are already working around these problems (weighed against apps that are already broken because of these problems). So I want to make sure that workarounds like the changes in this PR won't cause more trouble if the WebView starts behaving properly.

[jcesarmobile]

Of course in the last one the tab bar is partially hidden because safe-area-inset-bottom doesn't work on Android at the moment, so that's why some users are using plugins that provide the value of the safe areas to avoid them themselves.

yeah... I'm asking because I'm trying to get this fixed in Android WebView, and there are concerns about breaking apps that are already working around these problems (weighed against apps that are already broken because of these problems). So I want to make sure that workarounds like the changes in this PR won't cause more trouble if the WebView starts behaving properly.

I would assume that people using their own css variables for safe areas would be doing something like max(--custom-safe-area-inset-bottom, env(safe-area-inset-bottom)) so it works on iOS where safe-area-inset-bottom works and (presumably) --custom-safe-area-inset-bottom would be 0, so if it get fixed in the WebView, both would have the same value and nothing should change.

I would also assume that your fix would return 0 for the safe areas when the WebView is avoiding the safe areas as when using force/auto values of this PR. But I'm not sure if the plugins that create the css variables are also handling that possibility and return 0 in that case.

[robingenz]

I think we might want to use disable for 7 just because it is a behavior change, but I don't love it.

Yes, please disable it by default on Capacitor 7, as it would be a breaking change now and change that with Capacitor 8.

[jcesarmobile]

I've noticed that force also adjusts margins on Android 14 and probably other older versions, not sure if that's expected/desired.
It's not clear by the definition since it only talks about "settings" and not about Android versions, but I personally like that it does it as we have had complaints in the past about devices with notches or similar not behaving correctly (it was related to status bar plugin, but good to have this option in the core)

[markemer]

I've noticed that force also adjusts margins on Android 14 and probably other older versions, not sure if that's expected/desired. It's not clear by the definition since it only talks about "settings" and not about Android versions, but I personally like that it does it as we have had complaints in the past about devices with notches or similar not behaving correctly (it was related to status bar plugin, but good to have this option in the core)

Thanks! Yeah, I though "force" should do what it implies. All the time.

[ckoon-infopro]

@markemer How can I get this working? I have installed Capacitor 7.1.0 and tried setting adjustMarginsForEdgeToEdge to 'auto' and even 'force', but it doesn’t do anything. The margins are not applied.

[luisbytes]

I should also add the corresponding documentation, and I think it would be good to also add it to the upgrade guide since this fixes unexpected behavior in Capacitor v7

[TiBz0u]

Hi,
Is this code correct? If we found the attribute and the attribute is true, we don't add margin?

capacitor/android/capacitor/src/main/java/com/getcapacitor/CapacitorWebView.java

Line 71 in ab4e700

autoMargins = !(foundOptOut && optOutValue);

If I understand well, this attribute permits to opt out the edge-to-edge (thus disable it) and keep the same behavior than before.

Therefore, we have to add margin right? no?
The code should be :
autoMargins = (foundOptOut && optOutValue);

Kr

[jcesarmobile]

The attribute already does its own handling by itself, so the plugin will do nothing if the attribute is true to not conflict, unless you use "force", in that case the plugin will do its own handling, which might cause issues since it would be handled in two different ways.

[TiBz0u]

The attribute already does its own handling by itself, so the plugin will do nothing if the attribute is true to not conflict, unless you use "force", in that case the plugin will do its own handling, which might cause issues since it would be handled in two different ways.

Thanks for the clarification @jcesarmobile . I ended up with the same understanding after your comment.

However, why with auto, in case of Build.VERSION.SDK_INT < 35, margin is not added automatically?

My Samsung with Android 13 only shows correctly with force. However, as you stated, the margin can be handled twice in this scenario.

Kr.