VirtualKeyboard API: Control Mobile Keyboard Overlays

The VirtualKeyboard API provides web development teams with explicit control over how on-screen software keyboards interact with mobile web layouts. Traditionally, mobile browsers automatically shrink the visual viewport or abruptly shift page content when an on-screen keyboard appears, frequently breaking fixed-position elements, floating inputs, and chat interfaces. By allowing developers to opt out of this default browser behavior, the VirtualKeyboard API enables the keyboard to act as an overlay, exposing exact keyboard dimensions through JavaScript APIs and CSS environment variables so teams can design seamless, native-feeling user experiences.

The Problem with Default Mobile Keyboard Behavior

On mobile platforms like Android and iOS, the appearance of a software keyboard typically triggers one of two automatic browser behaviors: resizing the layout viewport or shifting the page viewport upward to keep the active input visible.

While functional for basic text documents, this behavior introduces severe limitations for modern web applications:

  • Layout Thrashing: Viewport resizing can cause rapid recalculations of full-height (100vh) elements.
  • Obscured UI: Sticky navigation bars, floating action buttons (FABs), and docked bottom inputs can be pushed off-screen or rendered underneath the keyboard.
  • Lack of Layout Fluidity: Developers have historically relied on fragile window.resize hacks or visualViewport event listeners to guess the keyboard’s state and height.

Taking Control with overlaysContent

The core feature of the VirtualKeyboard API is the ability to decouple the keyboard's appearance from the browser's viewport resizing engine. Developers can explicitly instruct the browser to treat the keyboard as a floating overlay above the page rather than an obstruction that resizes the layout.

This is achieved programmatically via JavaScript:

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
}

Once overlaysContent is set to true, the browser stops resizing the layout viewport when the keyboard opens. The webpage remains fully rendered at its standard size, allowing the development team to decide exactly which elements should move, resize, or stay stationary.

Styling Around the Keyboard with CSS Environment Variables

When the keyboard overlays the webpage, developers must ensure that focused inputs and critical interactive elements are not hidden beneath it. The VirtualKeyboard API addresses this by exposing native CSS environment variables that represent the keyboard's physical footprint:

  • env(keyboard-inset-top)
  • env(keyboard-inset-right)
  • env(keyboard-inset-bottom)
  • env(keyboard-inset-left)
  • env(keyboard-inset-width)
  • env(keyboard-inset-height)

These variables allow developers to reposition UI elements declaratively without relying on JavaScript animation loops. For example, a bottom-docked chat bar can smoothly adjust its position above the keyboard:

.bottom-docked-input {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  margin-bottom: env(keyboard-inset-height, 0px);
  transition: margin-bottom 0.1s ease-out;
}

If the keyboard is hidden, env(keyboard-inset-height) evaluates to 0px. When the keyboard appears, the element automatically offsets by the exact height of the software overlay.

Tracking Keyboard Geometry with JavaScript

For complex canvases, interactive games, or custom scrolling containers, CSS adjustments alone may not be sufficient. The VirtualKeyboard API provides a dedicated geometrychange event fired directly on navigator.virtualKeyboard.

Whenever the keyboard opens, closes, or changes orientation, the event triggers, exposing the keyboard's bounding rectangle:

navigator.virtualKeyboard.addEventListener("geometrychange", () => {
  const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
  
  if (height > 0) {
    console.log(`Keyboard visible: ${height}px high`);
  } else {
    console.log("Keyboard hidden");
  }
});

This precise rectangular data allows web engines to intelligently recalculate virtualized lists, dynamically reposition non-DOM elements, or adjust scroll bounds without interfering with the rest of the document flow.

Programmatic Keyboard Visibility

In addition to layout control, the API gives development teams direct control over the display state of the keyboard through two explicit methods:

  • navigator.virtualKeyboard.show()
  • navigator.virtualKeyboard.hide()

This eliminates the need to use artificial focus-shifting workarounds—such as focusing a hidden, dummy <input> element—to trigger the keyboard on custom-designed text fields or rich-text canvas editors.