VirtualKeyboard API

[leeyucha]

Description

The VirtualKeyboard API gives web apps fine-grained control when the on-screen keyboard appears, without relying on UA viewport resizing heuristics. It exposes:

navigator.virtualKeyboard.overlaysContent to opt out of automatic viewport adjustments,

geometrychange events plus boundingRect for keyboard geometry,

CSS env variables like env(keyboard-inset-height) to adapt layout purely with CSS.

This is critical for chat/messaging UIs, editors, and PWAs where input bars, FABs, or sticky footers are routinely occluded or cause scroll-jank. Aligning behavior across engines will remove a long-standing mobile web pain point and reduce site-specific workarounds. See MDN and Chrome docs for conceptual overview and examples.
MDN Web Docs
Chrome for Developers

Why now? Many complex apps (chat, editors, spreadsheets) still ship UA-specific hacks to avoid occlusion when the virtual keyboard appears. Interop on this API (events + CSS env vars + opt-out switch) would significantly reduce breakage and improve user experience across Android, iOS/iPadOS, ChromeOS, and desktop touch devices. (See references above.)

Specification

https://www.w3.org/TR/virtual-keyboard/

web-feature

https://web-platform-dx.github.io/web-features-explorer/features/virtual-keyboard/

Test Links

WPT live sample: virtual-keyboard/virtual-keyboard-type.https.html (checks navigator.virtualKeyboard type) — https://wpt.live/virtual-keyboard/virtual-keyboard-type.https.html
wpt.live

WPT directory (VirtualKeyboard API & policy tests) — reference: https://chromium.googlesource.com/.../wpt/+/refs/tags/epochs/daily/2024-06-09_01H/virtual-keyboard/
(contains tentative tests run with --enable-features=VirtualKeyboard)

Additional Signals

Shipping status (Chromium): Available since Chromium 94 on desktop & mobile (feature detection via navigator.virtualKeyboard).
Chrome for Developers

Mozilla standards-position: “Virtual Keyboard Control” discussion (tracking issue).
GitHub

WebKit: Request for position thread (2021) and WebKit bug tracking “Implement the VirtualKeyboard API”.
lists.webkit.org
WebKit Bugzilla

Spec maturity: W3C Web Editing WG Working Draft.
W3C

Problem background / developer pain points: MDN overview; in-depth article on fixing content occlusion.
MDN Web Docs
Ishadeed

Related work (complementary): interactive-widget viewport keyword (helps with resize policy; does not expose geometry).
Markup from hell - HTMHell

[github-actions]

This comment was automatically generated based on the information you provided. Please don't edit it.

Below is additional information about the web feature (from the web-features project) which is referenced in your proposal.
If this doesn't accurately correspond to your proposal, please update your initial comment to include web-features: <feature-id>.
To find feature IDs, use the web-features explorer.

Feature Virtual keyboard

• ID: virtual-keyboard
• Name: Virtual keyboard
• Description: The navigator.virtualKeyboard API inspects and controls on-screen virtual keyboards. You can use it to programmatically hide or show a virtual keyboard or respond to the keyboard disappearing or appearing.
• Baseline status: Limited Availability
• Docs: VirtualKeyboard API
• Standard positions: WebKit
• Chrome use counter: chromestatus.com
• More information: See the web-features explorer

[foolip]

Thanks you @leeyucha for submitting this proposal! I've gone ahead and updated the description to link to https://web-platform-dx.github.io/web-features-explorer/features/virtual-keyboard/ in the web-features section. This was to help the bot (above) find the right feature and link some additional resources.

[birtles]

As a Web developer who has tried using this API, I am concerned that it is not suitable for Interop because:

• It requires testing on mobile devices in order to be useful, something which I believe is not currently covered by Interop. For example, in my testing, the Chrome for Android implementation:

  • Reports the wrong height of the keyboard
  • Gets the screen height wrong while transitioning
  • Produces flicker

  Unless implementations can be tested for consistent behavior in these areas, it doesn't seem meaningful to include it in Interop.

• The dispatch of geometrychange events is undefined (see Where is the dispatch of geometrychange events defined? w3c/virtual-keyboard#21)

• The editors appear unresponsive (e.g. see above issue or the TAG response)

Code comments from last time I tried to use this API in an app

  // Wait for the keyboard to appear.
  //
  // This is needed for three reasons:
  //
  // 1) On Chrome for Android, if we fetch the keyboard bounding box immediately
  //    the keyboard will not be shown yet and we'll get back a zero height. If
  //    we wait about 50~100ms we'll normally get the correct height.
  //
  // 2) Also on Chrome for Android, if we attempt to get the
  //    `window.innerHeight` etc. while the keyboard is still being shown we'll
  //    get back the wrong values.
  //
  //    Specifically at least the following values:
  //
  //    - window.innerHeight
  //    - window.visualViewport.height
  //    - screen.height
  //    - document.documentElement.clientHeight
  //
  //    are all off, by (roughly) the height of the virtual keyboard.
  //
  //    That is, when the keyboard first shows, the heights returned will be the
  //    correct height PLUS the height of the virtual keyboard.
  //
  //    Similarly when the keyboard is hidden, the heights will be the correct
  //    height MINUS the height of the virtual keyboard.
  //
  //    My guess is that Chrome for Android is temporarily establishing a larger
  //    (or smaller) canvas and using that for introducing the virtual keyboard
  //    in combination with windowSoftInputMode="adjustResize" (which also might
  //    explain the flicker).
  //
  //    Now we could just add or subtract the height of the virtual keyboard but
  //    it's not clear if this Chrome behavior is intentional (I suspect it's
  //    not) or likely to be implemented consistently if other browsers ever
  //    implement this API (seems unlikely) so instead we're best off just
  //    waiting until we get sane values. ~150ms or so seems to be enough for
  //    that.
  //
  // 3) Yet again on Chrome for Android, if we attempt to call
  //    `elem.scrollBy()` too soon, it simply gets ignored. We need to
  //    wait for a stable state before calling it. 300ms seems to be enough.
  //
  // So if we simply wait about 300ms at the start then we should be in a stable
  // state where we get (mostly, see below) sane values.

And

  // Chrome for Android's implementation gives me back a bounding box with
  // a top/y value of 51 and I can't for the life of me find out what that
  // 51px is relative to.
  //
  // The spec is ill-defined and it appears the TAG didn't even approve it?
  //
  // They say their concerns have NOT been addressed [1] and closed it with
  // an 'ambivalent' status.[2]
  //
  // [1] https://github.com/w3ctag/design-reviews/issues/507#issuecomment-804723066
  // [2] https://github.com/w3ctag/design-reviews/issues/507#issuecomment-805930002
  //
  // So, instead we just assume that virtual keyboards always appear at the
  // bottom of the screen, ignore the top/y value and calculate the actual
  // position using the window height.

[yulunwu2]

https://wpt.fyi/results/virtual-keyboard?label=master&label=experimental&aligned&q=virtual%20keyboard

[wpt-interop]

Thank you for proposing VirtualKeyboard API for Interop 2026.

We want to let you know it was not selected to be part of Interop this year.

On behalf of the entire Interop team, thank you for submitting it for consideration. We got many more proposals than we could include in this year's project, necessitating some difficult choices. Please note this should not be taken as a comment on the technology as a whole, or our willingness to consider it for Interop in the future. We appreciate the work you put into your proposal, and would welcome your participation in future rounds of Interop.

Posted on behalf of the Interop team.