Handling Android Soft Keyboard Layout Shifts in TWAs

When web developers transition their Progressive Web Apps to the Google Play Store using a Trusted Web Activity, they often encounter differences in how the underlying Android operating system interacts with web layouts. One of the most common friction points is the behaviour of the system virtual keyboard, also known as the soft keyboard. On mobile devices, the appearance of this keyboard can alter the viewport, causing fixed navigation bars, input fields, and action buttons to shift, resize, or disappear completely.

Understanding how the Android system and modern web engines handle keyboard inputs is essential to building a native-feeling application. This guide details the mechanics of viewport resizing in TWAs, how to configure the Android Manifest to control window adjustment, and modern web APIs that help maintain layout stability.

How Android Handles the Soft Keyboard

By default, when an input field receives focus inside a Trusted Web Activity, the Android system must decide how to make room for the soft keyboard. Because the keyboard occupies a significant portion of the screen, the application window must adapt. Android manages this through the window soft input mode, which is configured in the Android app source code.

There are two primary modes that affect the web layout:

• adjustResize: The application window is resized to make room for the soft keyboard. This reduces the height of the container holding your PWA, triggering a layout change in the web view.
• adjustPan: The application window is not resized. Instead, the window is panned or shifted upward so that the current input focus is visible. This does not change the layout viewport dimensions, but parts of your application may be panned off-screen.

For most PWAs, adjustResize is the preferred and default configuration because it allows the browser engine to adjust the layout dynamically. However, this resize event changes the CSS viewport height, which can compress layouts, warp background images, or push bottom-anchored navigation menus directly on top of the keyboard.

The Viewport Interactive Widget Attribute

Historically, web developers had limited control over how the browser engine reacted to the virtual keyboard. Fortunately, modern browsers running inside Android TWAs now support the interactive-widget key within the viewport meta tag. This allows developers to explicitly declare how the keyboard interaction impacts the page layout.

You can define this property in the HTML head of your PWA:

<meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content">

There are three values available for the interactive-widget attribute:

By utilising resizes-visual or overlays-content, you can prevent your entire page layout from collapsing when a user taps a form input field, keeping your headers, footers, and sidebars stable.

Managing Viewports with CSS and JS

Relying solely on viewport meta tags may not solve all layout quirks, especially when dealing with complex single-page applications. When the keyboard resizes the viewport, elements sized with viewport height units (such as vh) will scale down instantly. To prevent this, you can adopt modern CSS viewport units and JavaScript detection APIs.

Instead of standard viewport height units, use Dynamic Viewport units such as dvh, Small Viewport units svh, and Large Viewport units lvh. The small viewport height represents the screen size assuming the keyboard or browser dynamic bars are visible, whereas the large viewport height assumes they are hidden. This gives you finer control over minimum and maximum dimensions.

Additionally, you can use the Visual Viewport JavaScript API to monitor changes in real-time. This is particularly useful for positioning custom floating elements or adjusting scroll positions dynamically when the soft keyboard appears:

window.visualViewport.addEventListener('resize', () => { const keyboardHeight = window.innerHeight - window.visualViewport.height; if (keyboardHeight > 0) { document.body.style.setProperty('--keyboard-height', keyboardHeight + 'px'); } else { document.body.style.setProperty('--keyboard-height', '0px'); } });

By binding this listener, you can dynamically apply CSS variables that adjust bottom paddings or hide non-essential elements when the keyboard is active, smoothing out the user transition.

Best Practices for Form UX in Android TWAs

To ensure a frictionless input flow in your converted Android app, follow these practical structural guidelines:

• Avoid Fixed Bottom Menus on Input Screen: Hide bottom-docked tab bars when input fields are focused. You can achieve this using CSS focus-within selectors or simple JavaScript class toggles.
• Ensure Scrollability: Always wrap forms in scrollable containers. If the keyboard occupies 50% of the screen, the user must still be able to scroll through the remaining form fields.
• Use Semantic Input Types: Set correct inputmode and type attributes (such as inputmode="numeric", type="email"). This ensures the correct system keyboard layout is shown, reducing typing errors and unnecessary keyboard height switches.
• Disable Auto-Focus on Page Load: Automatically opening the keyboard on page transitions can disorient users and cause sudden layout shifts before the page is fully rendered.

By implementing these adjustments directly in your web codebase, the changes will immediately propagate to your active Android app, eliminating the need to compile, sign, and resubmit new APK or AAB binaries to the Google Play Store.