# VirtualKeyboard API

> How the VirtualKeyboard API lets a page opt out of automatic viewport resizing and read the on-screen keyboard's geometry, with Chrome/Firefox/Safari support.

**In one line:** per MDN, the VirtualKeyboard API provides control over an application's
layout when the on-screen virtual keyboard appears and disappears; browsers usually adjust
the viewport height and scroll focused inputs into view.

## What it is

The API is exposed as `navigator.virtualKeyboard`, an instance of the `VirtualKeyboard`
interface. Per MDN, setting `navigator.virtualKeyboard.overlaysContent = true` tells the
browser to stop resizing the viewport when the on-screen keyboard appears, so the
keyboard instead overlays the page. MDN documents the companion pieces: a
`boundingRect` property that reports the keyboard's current on-screen rectangle, a
`geometrychange` event fired whenever that rectangle changes, and `show()` / `hide()`
methods to request that the keyboard appear or disappear programmatically.

## Where it is supported

Per MDN's browser-compat-data, `navigator.virtualKeyboard` is supported from Chrome 94 (and
Chrome for Android 94) and from Edge 94, since Edge tracks Chromium's implementation. The
same file marks Opera, Opera Android, Samsung Internet, Android WebView, and the Meta Quest
Browser as `"mirror"` for this feature, meaning their support tracks Chromium's version
rather than being listed separately — so support extends across the Chromium family, not
just Chrome and Edge. Firefox and Safari are recorded as unsupported, with
`https://bugzil.la/1730568` and `https://webkit.org/b/230225` listed as implementation
URLs. The sub-features `boundingRect`, the `geometrychange` event, `hide()`,
`overlaysContent`, and `show()` all share this identical Chromium-family support pattern
in the same compat-data file.

## How to use it

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

  navigator.virtualKeyboard.addEventListener("geometrychange", (event) => {
    const { x, y, width, height } = event.target.boundingRect;
    document.documentElement.style.setProperty("--keyboard-height", `${height}px`);
  });
}
```

## How to detect it at runtime

Feature-detect `navigator.virtualKeyboard` before touching `overlaysContent`, and retain
the platform's default behavior when it is absent:

```js
function supportsVirtualKeyboardApi() {
  return "virtualKeyboard" in navigator;
}

if (supportsVirtualKeyboardApi()) {
  navigator.virtualKeyboard.overlaysContent = true;
} else {
  // No VirtualKeyboard API here — retain the browser's default behavior
  // and avoid layout code that assumes an overlaying keyboard.
  document.documentElement.classList.add("uses-viewport-resize-keyboard");
}
```

## Practical checklist

- Per MDN's compat data, this API is Chromium-only today (Chrome and Edge from version 94,
  with Opera, Samsung Internet, Android WebView, and the Meta Quest Browser mirroring that
  same Chromium support); Firefox and Safari are recorded as unsupported, with
  implementation URLs listed for each.
- Setting `overlaysContent = true` opts your page out of automatic viewport resizing
  entirely — without also handling `geometrychange` to reposition fixed input fields,
  controls can end up hidden behind the keyboard.
- Per MDN, `boundingRect` is a `DOMRect` that describes the virtual keyboard's current
  geometry.
- Per MDN, `show()` and `hide()` manually control showing and hiding the virtual keyboard.

## Where to go next

- [Media Session API](/reference/capabilities/media-session/)