Keyboard Space on Cold Start

[ubrandon]

When starting my app up cold, there is a space where the keyboard should be and it doesnt disappear until I open it again. This happens on Android with keyboardResize:True in the config.

What is the recommended settings for the keyboard on Android to make it work the best with Cap 8? I tried all the options and there is a unique bug on every combination with the keyboard.

If keyboardResize:True
Then everything works, the screens is resized, but on startup we get a huge space that is unusable

If keyboardResize:False
Then the keyboard pushes the footer up much smoother, but it pushes the entire page up and the top nav disappears and there is a bug where sometimes the keyboard covers the footer. 🤦

[MukundaKatta]

This is a known interaction between Android's adjustResize windowing and WebView loading order on Capacitor 8. A few specific things usually resolve it:

Why the gap appears with keyboardResize: true

With keyboardResize: 'body' (the default) or the old resize: 'body', Capacitor tells the Android window to treat the WebView as if the keyboard is always potentially present, so the body can shrink. At cold-start there's a race:

1. Activity starts, sets softInputMode = adjustResize.
2. WebView loads and paints at the initial pre-keyboard height.
3. Keyboard visibility state is still reporting "hidden" but the inset hasn't settled — Android leaves a bottom window inset that equals the last keyboard height (cached from the previous app launch or system default).
4. The gap you see is that stale bottom inset.

Once you focus any input and dismiss the keyboard, Android recomputes insets correctly, and the gap disappears.

Config combination that actually works on Cap 8 Android

// capacitor.config.json
{
  "plugins": {
    "Keyboard": {
      "resize": "native",             // resize the Android window itself, not the WebView body
      "style": "DARK",                // or LIGHT
      "resizeOnFullScreen": true
    }
  }
}

resize: 'native' is the option that generally avoids the cold-start inset issue on Android in Cap 7+. It uses ADJUST_RESIZE for the native window and doesn't try to emulate it in JS, so there's no phantom bottom padding before the first keyboard event.

If native is too coarse (it resizes the Activity, which can affect your top nav), the next-best alternative is:

{
  "plugins": {
    "Keyboard": {
      "resize": "ionic",
      "resizeOnFullScreen": true
    }
  }
}

ionic mode pairs ADJUST_RESIZE with CSS-variable-based padding (--ion-safe-area-bottom), giving you finer-grained control but requiring you to consume the variable in your layout.

The cold-start gap specifically

If the gap still appears on cold-start with resize: 'native', add an explicit keyboard hide on app ready:

// app/layout.tsx or a bootstrap file that runs before the first paint
import { Keyboard } from '@capacitor/keyboard'
import { App } from '@capacitor/app'

App.addListener('appStateChange', (state) => {
  if (state.isActive) Keyboard.hide().catch(() => {})
})

// Also on very first run:
document.addEventListener('deviceready', () => Keyboard.hide().catch(() => {}))
Keyboard.hide().catch(() => {})  // idempotent; safe to call even if it's already hidden

The Keyboard.hide() call doesn't actually hide a visible keyboard (there isn't one) — it forces Android to recompute softInputMode and clear the stale inset. That's the mechanism of the fix.

AndroidManifest tweak for the nav-disappearing case

For your resize: false scenario (keyboard pushes everything up, top nav disappears), what you're seeing is ADJUST_PAN behaviour. You can't get both behaviours simultaneously from a single mode, but you can mark your top nav as "stick to the screen":

<!-- android/app/src/main/AndroidManifest.xml -->
<activity
    android:name=".MainActivity"
    android:windowSoftInputMode="adjustResize"
    ...>

Forcing adjustResize in the manifest and using resize: 'native' in Capacitor keeps the activity resizing (so top nav stays) while the WebView gets the corrected inset. Top-nav disappearance usually traces back to adjustPan being active.

Diagnostic that pins down which one you're hitting

Enable Android's window inset logging:

adb shell settings put system window_animation_scale 1
adb logcat -s ViewRootImpl:D WindowManager:D

Then cold-start the app. You'll see lines like:

ViewRootImpl: Inset: content=(0,0,0,X) visible=(0,0,0,Y)

If X is non-zero on cold-start and becomes zero only after the first keyboard open/close cycle, it's the stale-inset bug — fix with the Keyboard.hide() bootstrap above. If X alternates erratically between cold-start and resume, it's usually a webview-height mismatch — resize: 'native' + manifest adjustResize is the combination.

TL;DR

• Try Keyboard.resize: 'native' first — resolves the cold-start gap in most projects.
• If that affects top nav, use ionic resize with safe-area CSS variables.
• Defensive Keyboard.hide() on app start + appStateChange cleans up any residual stale insets.

On Android/Capacitor 8 that combination has been stable across the projects I've shipped. The single-mode approach (only adjustResize or only adjustPan) almost always leaves one edge case ugly; the two-layer approach above handles both cold-start and mid-session correctly.