fix: resolve issues with safe area / systembars plugin by tafelnl · Pull Request #8535 · ionic-team/capacitor

tafelnl · 2026-07-21T13:05:24Z

This resolves some (most/all maybe even) current issues with the safe area / systembars plugin. These changes have been battle tested in production for several months now.

Closes #8525
Closes #8528
Closes #8416
Closes ionic-team/capacitor-keyboard#68
Closes ionic-team/capacitor-keyboard#61
Closes ionic-team/capacitor-keyboard#46
Closes ionic-team/capacitor-keyboard#28
Closes ionic-team/capacitor-keyboard#53
Closes ionic-team/capacitor-keyboard#57

And potentially some more. I haven't had time to look at all issues.

We already had a conversation about some of these design approaches earlier on. See #8268 and #8384 (comment)

tafelnl · 2026-07-21T13:07:37Z

+        if (isSafeAreaPluginPresent()) {
+            Logger.warn(
+                "SystemBars",
+                "You should uninstall `@capacitor-community/safe-area`. Having this library installed can lead to unexpected behavior."


Having this warning here seems fair to me, as the two are strictly incompatible and there are still loads of users installing the community plugin

Ended up removing this warning. Because, actually, I think it makes more sense to solve this using an updating peerDependencies policy in the plugin itself. Nonetheless it might be good to mention somewhere in the docs that the use of (any) third party safe area plugins is discouraged. And if a developer wants to use such a plugin, that insetsHandling should be set to disable to prevent interference

tafelnl · 2026-07-21T13:08:22Z

                    .build();
            }

-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {


I'm still not sure what this if-statement was meant for. I asked about it a few times in other PRs but never got a response, so I dont know the rationale behind it. Seems unnecessary to me. Moreover, it seems to be the root cause of many bug reports

There were some internal requirements we had to adhere to. Its not necessary anymore.

tafelnl · 2026-07-21T13:09:04Z

+     *
+     * @default false
+     */
+    initialViewportFitCover?: boolean;


This one is really important to prevent layout jumps

Ended up renaming this to initialViewportFitValueHint (in 7abde6f) because it sounds a bit more logical

tafelnl · 2026-07-21T13:10:13Z

+        if (!systemBarsInsetsHandling.equals("disable") && keyboardResizeOnFullScreen) {
+            Logger.warn(
+                "SystemBars",
+                "You should omit `Keyboard.resizeOnFullScreen` in your `capacitor.config.json`. Other values can lead to unexpected behavior."


As I mentioned before, I think this config value should be deprecated altogether. If you still want it, I think it makes much more sense to include it in this plugin to prevent future bugs and resolve present bugs

We've had discussions about this internally, and we agree. We'll get to it eventually. For now, this warning will do.

tafelnl · 2026-07-22T05:45:03Z

-            Insets safeAreaInsets = calcSafeAreaInsets(newInsets);
-            injectSafeAreaCSS(safeAreaInsets.top, safeAreaInsets.right, safeAreaInsets.bottom, safeAreaInsets.left);


I simplified this, because it was doing redundant recalculations which caused bugs across different webview versions

Vissie2 · 2026-07-22T11:17:16Z

@theproducer

tafelnl · 2026-07-24T14:13:39Z

We might want to call EdgeToEdge.enable(this) inside BridgeActivity.onCreate (if insetsHandling !== 'disable'). Because it's easy to forget. See #8522 for example.

However, one could argue that it's breaking change. In that case, it should then be documented somewhere, and instead be added in Capacitor v9.

On the other hand, your app will express unexpected behavior when not calling EdgeToEdge.enable(this), and there already were quite a few breaking changes in non-major updates in Capacitor v8 regarding the safe area. So it might make sense to add it nonetheless

Just to reduce the amount of churn and potential for upstream breaking changes for some of the other teams depending on Capacitor 8 currently, I'll just make note of this in the docs. We'll make all of this default in Cap 9.

Sounds good!

…ortFitValueHint`

riderx · 2026-08-13T00:38:30Z

you can try to make a patch with https://capgo.app/docs/plugins/capacitor-patch/ to use it and get it or https://github.com/Cap-go/capacitor-plus merged to capacitor

…rred conflicts)

…rite Upstream ionic-team#8535 removed navBarVisible state; tests that reflected on the private field caused NoSuchFieldException in test-android. Keep hide/show WindowInsetsController coverage. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

…rred conflicts)

Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

…rred conflicts)

theproducer

Thanks for consolidating and drilling down these edge to edge bugs!

theproducer · 2026-09-09T20:13:48Z

+        if (!systemBarsInsetsHandling.equals("disable") && keyboardResizeOnFullScreen) {
+            Logger.warn(
+                "SystemBars",
+                "You should omit `Keyboard.resizeOnFullScreen` in your `capacitor.config.json`. Other values can lead to unexpected behavior."


We've had discussions about this internally, and we agree. We'll get to it eventually. For now, this warning will do.

theproducer · 2026-09-10T13:56:45Z

                    .build();
            }

-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {


There were some internal requirements we had to adhere to. Its not necessary anymore.

…l/capacitor into fix/resolve-issues-with-safe-area

tafelnl · 2026-09-10T17:46:10Z

Thanks for consolidating and drilling down these edge to edge bugs!

🎉 you're welcome!

And thank you for taking the time to review it and making it happen. Appreciated!

Merge upstream 8.5.2 (5e0f678) into the safe-area/edge-to-edge PR branch. Integrates upstream ionic-team#8535 (safe area / systembars fixes) while keeping the branch architecture (legacy API 21-34 support, margins + CSS variables, keyboard via CSS, no window padding): - Add 'native' insetsHandling mode: safe area handling delegated to the platform/WebView, insets passed through untouched, no CSS variables injected, and setDecorFitsSystemWindows(true) is no longer forced so apps can opt into native edge-to-edge (env(safe-area-inset-*)). - Add 'initialViewportFitValueHint' config to pre-seed hasViewportCover and prevent layout shifts on first paint. - Adopt single-webViewListener registration (prevents duplicate listeners across start cycles) gated on 'disable'. - Move viewport-fit detection from the removed @JavascriptInterface onDOMReady() into onPageCommitVisible (drop CapacitorSystemBarsAndroidInterface). - Add warnAboutUnsupportedConfigurationValues() for Keyboard.resizeOnFullScreen. - Keep: requested-style storage (DEFAULT follows system theme), nav bar resource-height fallback for API<30, pre-Oreo IME visibility handling, cached WebView major version with NumberFormatException safety, hardened CSS variable injection (removeProperty + duplicate cleanup). Validation: compileReleaseJavaWithJavac, lintRelease, testRelease pass.

seravifer · 2026-09-15T10:04:05Z

Hi, after upgrading to 8.5.2 we hit a regression that we traced to the listener move in this PR, filed as #8603.

On API < 30, attaching the OnApplyWindowInsetsListener to the decor view exposes it to the window-level SYSTEM_UI_FLAG_LAYOUT_* flags that androidx EdgeToEdge.enable() sets. LAYOUT_HIDE_NAVIGATION drops the navigation bar from the window's system-window insets, so insets.getInsets(systemBars() | displayCutout()).bottom arrives as 0 while the navigation bar is visible, and web content renders underneath it. The top inset is unaffected, and API 30+ is fine because WindowInsetsCompat there uses the real WindowInsets.getInsets(Type) API.

Measured on a PAX A920Pro (Android 10, WebView 147): env(safe-area-inset-bottom) = 0 with a 48dp navigation bar drawn over the window.

tafelnl commented Jul 21, 2026

View reviewed changes

Comment thread core/system-bars.md

tafelnl commented Jul 21, 2026

View reviewed changes

Comment thread android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java

tafelnl commented Jul 21, 2026

View reviewed changes

Comment thread android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java

tafelnl commented Jul 21, 2026

View reviewed changes

tafelnl commented Jul 22, 2026

View reviewed changes

theproducer self-assigned this Jul 22, 2026

This was referenced Jul 24, 2026

[Bug]: safe area variables are calculated incorrectly with SplashScreen native plugin on Android 12 (WebView 140+) #8522

Open

[Bug]: Capacitor v8.3.0 extra gray space when keyboard is visible #8525

Closed

tafelnl commented Jul 24, 2026

View reviewed changes

tafelnl force-pushed the fix/resolve-issues-with-safe-area branch 2 times, most recently from c202f7f to 7abde6f Compare July 27, 2026 06:48

This was referenced Aug 2, 2026

Follow-ups for #8535: css default, doc annotations, EdgeToEdge.enable tafelnl/capacitor#1

Open

[Bug]: Edge-To-Edge-Mode not working #8416

Closed

tafelnl added 8 commits August 4, 2026 16:22

fix: resolve issues with safe area plugin

00ccd30

style: run npm run fmt

e3e5a50

chore: run npm run build:nativebridge

d58a686

docs: update documentation

d59bcd1

typo

2e9053f

fix: make InsetsHandling.css work correctly

a08187a

refactor: improve warning about unsupported values

b7e9818

feat: remove detectViewportFitCoverChanges and rename `initialViewp…

9b35343

…ortFitValueHint`

tafelnl force-pushed the fix/resolve-issues-with-safe-area branch from 7abde6f to 9b35343 Compare August 4, 2026 14:22

fix: whoops

4d9996b

tafelnl force-pushed the fix/resolve-issues-with-safe-area branch from 7b2d246 to 4d9996b Compare August 4, 2026 14:25

ingalls mentioned this pull request Aug 12, 2026

Keyboard Retraction dfpc-coe/CloudTAK#1662

Merged

tafelnl mentioned this pull request Aug 22, 2026

Android: native-padding branch dispatches a live IME inset, so the WebView subtracts the keyboard twice (sibling of #107, other branch) capacitor-community/safe-area#109

Closed

Merge branch 'main' into fix/resolve-issues-with-safe-area

a2c3e9a

riderx mentioned this pull request Aug 25, 2026

chore: sync upstream PR #8535 - fix: resolve issues with safe area / systembars plugin Cap-go/capacitor-plus#120

Open

fix: whoops

cbc8257

tafelnl commented Aug 25, 2026

View reviewed changes

Comment thread cli/src/declarations.ts

fix: typo

897c731

riderx pushed a commit to Cap-go/capacitor-plus that referenced this pull request Aug 26, 2026

chore: sync upstream PR ionic-team#8535 from @tafelnl (upstream-prefe…

304f151

…rred conflicts)

riderx pushed a commit to Cap-go/capacitor-plus that referenced this pull request Aug 27, 2026

chore: sync upstream PR ionic-team#8535 from @tafelnl (upstream-prefe…

9fe04e4

…rred conflicts)

cursor Bot pushed a commit to Cap-go/capacitor-plus that referenced this pull request Aug 27, 2026

fix: sync upstream PR ionic-team#8535 systembars/safe area changes only

c740729

Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

riderx pushed a commit to Cap-go/capacitor-plus that referenced this pull request Aug 28, 2026

chore: sync upstream PR ionic-team#8535 from @tafelnl (upstream-prefe…

b25844a

…rred conflicts)

theproducer changed the base branch from main to next September 8, 2026 20:49

theproducer changed the base branch from next to main September 8, 2026 21:22

theproducer approved these changes Sep 10, 2026

View reviewed changes

theproducer and others added 5 commits September 10, 2026 08:58

Merge branch 'main' into fix/resolve-issues-with-safe-area

ca67e2a

adding documentation note

b912378

Merge branch 'fix/resolve-issues-with-safe-area' of github.com:tafeln…

46ca94a

…l/capacitor into fix/resolve-issues-with-safe-area

Merge branch 'main' into fix/resolve-issues-with-safe-area

2a50c83

Merge branch 'main' into fix/resolve-issues-with-safe-area

5744b78

theproducer merged commit e37d9c6 into ionic-team:main Sep 10, 2026
6 checks passed

theproducer mentioned this pull request Sep 11, 2026

feat(SystemBars): set default insets handling to 'native' #8599

Merged

9 tasks

OS-pedrogustavobilro mentioned this pull request Sep 11, 2026

Fix navigation bar overlay in edge-to-edge mode on Android #8454

Closed

8 tasks

luisbytes mentioned this pull request Sep 12, 2026

Bug: Double safe-area padding on Android 14 and below with Capacitor 8.5.2 swaplab-engine/capacitor-admob-nextgen#7

Open

seravifer mentioned this pull request Sep 15, 2026

[Bug]: SystemBars reports a zero bottom inset on API < 30 when the app uses EdgeToEdge.enable() (content renders under the navigation bar) #8603

Open

3 tasks

GuilhermeAbreu mentioned this pull request Sep 23, 2026

SystemBars: passthrough IME resize (viewport-fit=cover) ignores View.setPadding()/rewritten insets on some devices #8622

Open

luisbytes mentioned this pull request Sep 24, 2026

bug: Android banner safe-area issues with Capacitor 8.5.2+ and different WebView versions capacitor-community/admob#468

Open

		Insets safeAreaInsets = calcSafeAreaInsets(newInsets);
		injectSafeAreaCSS(safeAreaInsets.top, safeAreaInsets.right, safeAreaInsets.bottom, safeAreaInsets.left);

Conversation

tafelnl commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tafelnl Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tafelnl Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tafelnl Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tafelnl Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tafelnl Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Vissie2 commented Jul 22, 2026

Uh oh!

tafelnl Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

riderx commented Aug 13, 2026

Uh oh!

Uh oh!

theproducer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tafelnl commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

seravifer commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tafelnl commented Jul 21, 2026 •

edited

Loading

tafelnl Jul 21, 2026 •

edited

Loading

tafelnl Jul 27, 2026 •

edited

Loading

tafelnl Jul 21, 2026 •

edited

Loading

tafelnl Jul 27, 2026 •

edited

Loading

tafelnl Jul 21, 2026 •

edited

Loading

tafelnl Jul 24, 2026 •

edited

Loading

tafelnl commented Sep 10, 2026 •

edited

Loading

seravifer commented Sep 15, 2026 •

edited

Loading