VirtualKeyboard API

This section is non-normative.

The Virtual Keyboard (VK) is the on-screen keyboard used for input in scenarios where a hardware keyboard may not be available. User agents respond to the presence of the VK, without any exposure of this information to web developers in the following way: 1. Repositioning the user agent above the VK 2. Reducing the size of the layout viewport so the VK doesn't occlude it 3. Reducing the size of the visual viewport and padding the layout viewport to ensure it can be shifted above the VK This API provides a fourth option that allows the user agent to leave its layout and visual viewports unchanged and instead provide information about the intersection of the VK and layout viewport so that the author can adapt the layout of their web pages using JavaScript or CSS environment variables.

Figure showing virtual keyboard on dual screen device

Figure showing virtual keyboard on single-touch screen device

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST and MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

WebIDLpartial interface Navigator {
    [SecureContext, SameObject] readonly attribute VirtualKeyboard virtualKeyboard;
};
[Exposed=Window, SecureContext]
interface VirtualKeyboard : EventTarget {
    undefined show();
    undefined hide();
    readonly attribute DOMRect boundingRect;
    attribute boolean overlaysContent;
    attribute EventHandler ongeometrychange;
};

The VirtualKeyboard object has an associated:

A DOMRect, initially has zero values.

A boolean, initially false. When this attribute is set to true, a user agent MUST NOT resize its document's viewport or visual viewport.

show() method

The method must follow these steps:

1. Let window be this's relevant global object. Assert that window is a Window object.
2. If window does not have sticky activation, abort these steps.
3. If the focused element is not a form control (such as the value of the textarea element), or an editing host (e.g., using contenteditable) then abort these steps.
4. If the virtualKeyboardPolicy is not manual or inputMode's attribute value is none then abort these steps.
5. Call the system API to show the VK.
6. In parallel, follow these steps:
   1. Wait for the virtual keyboard to be shown by the system.
   2. Call set the virtual keyboard bounding rect with the keyboard's OS reported bounding rectangle and the document's viewport rectangle.
   3. Fire an event named "geometrychange" at this.

hide() method

The method must follow these steps:

1. Let window be this's relevant global object. Assert that window is a Window object.
2. If window does not have sticky activation, abort these steps.
3. If the focused element's virtualKeyboardPolicy is not manual or inputMode's attribute value is none then abort these steps.
4. Call the system API to hide the VK.
5. In parallel, follow these steps:
   1. Wait for the virtual keyboard to be hidden by the system.
   2. Call set the virtual keyboard bounding rect with the keyboard's OS reported bounding rectangle (which has all 0 values) and the document's viewport rectangle.
   3. Fire an event named "geometrychange" at this.

Note

Platform heuristics may impose additional restrictions on VK show() and hide(). e.g., on Windows the pointer type MUST be touch or pen.

Note

A few people have expressed concerns around show() and hide() methods not being promise-based, but we believe it is a better design for web developers to use ongeometrychange event since it is fired when VK visibility changes, making the return values unnecessary.

overlaysContent

The overlaysContent getter steps are to return this's overlaysContent.

The overlaysContent setter steps are to set this's overlaysContent to the given value.

boundingRect

The attribute reports the intersection of the VK with the document's viewport in client coordinates. Call set the virtual keyboard bounding rect.

set the virtual keyboard bounding rect

To set the virtual keyboard bounding rect, with osk (a DOMRect representing the on-screen keyboard rectangle), and lv (a DOMRect representing the document's viewport rectangle) as inputs, run the following steps:

1. Let osk be the on-screen keyboard rectangle that is the result of running the algorithm in show() or hide() on this.
2. Let lv be the document's viewport that is the result of running the algorithm in show() or hide() on this.
3. Map osk to the coordinate space of lv.
4. Let bounds be a DOMRect object.
5. Update bounds by intersecting lv with the osk.
6. Map bounds to the coordinate space of lv.
7. Return bounds.

The boundingRect getter steps are to return this's boundingRect.

ongeometrychange

The event is dispatched when the intersection of the VK and the document's viewport changes, e.g., in response to the VK being shown or hidden or the browser window being repositioned.

WebIDL partial interface mixin ElementContentEditable {
     [CEReactions] attribute DOMString virtualKeyboardPolicy;
};

The virtualKeyboardPolicy is an enumerated attribute whose keywords are the empty string, auto, and manual. The IDL attribute must reflect the respective content attributes of the same name. When specified on an element that is a contenteditable host, auto causes the corresponding editable element to automatically show the VK when it is focused or tapped & manual decouples focus and tap on the editable element from changes in the VK’s current state - the VK remains as it was.
The change in setting of any virtualKeyboardPolicy attribute value, negates currently defined behavior, unless it is a change from auto to empty string or vice versa.

• When auto enumerated attribute is set, the VK is handled by the browser.
• When manual enumerated attribute is set, it prevents the default handling of the VK in a browser and needs to be handled by the script.
• When empty string enumerated attribute is set, the VK is handled by the browser.

The VirtualKeyboard API proposes six new CSS environment variables that the web developers can utilize to calculate the virtual keyboard's size and adjust layout in a declarative way.