Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
The VirtualKeyboard
API provides authors with greater control over the visibility of the virtual keyboard (VK), and greater ability to adapt the layout of web pages when VK visibility changes.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Web Editing Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-editing-tf@w3.org (subscribe, archives).
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 15 September 2020 W3C Process Document.
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.)
VirtualKeyboard
InterfaceWebIDL
[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:
boundingRect
A DOMRect
, initially has zero values.
overlaysContent
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:
Window
object.
virtualKeyboardPolicy
is not manual
or inputMode's attribute value is none then abort these steps.
set the virtual keyboard bounding rect
with the keyboard's OS reported bounding rectangle and the document's viewport rectangle.hide()
method
The method must follow these steps:
Window
object.
virtualKeyboardPolicy
is not manual
or inputMode's attribute value is none then abort these steps.
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.
Platform heuristics may impose additional restrictions on VK show
()
and hide
()
. e.g., on Windows the pointer type MUST be touch or pen.
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.
The overlaysContent
getter steps are to return this's overlaysContent
.
The overlaysContent
setter steps are to set this's overlaysContent
to the given value.
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:show
()
or hide
()
on this.
show
()
or hide
()
on this.
DOMRect
object.
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.
ElementContentEditable
mixinWebIDL partial interface ElementContentEditable
{
[CEReactions] attribute DOMString virtualKeyboardPolicy
;
};
Add handling of input and textarea.
The virtualKeyboardPolicy
is an enumerated attribute whose keywords are the 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.
Specify timing relative to events like focus.
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.
These CSS env should be added to the CSS env variable spec.
Name | Value |
---|---|
keyboard-inset-top | length |
keyboard-inset-right | length |
keyboard-inset-bottom | length |
keyboard-inset-left | length |
keyboard-inset-width | length |
keyboard-inset-height | length |
The keyboard insets are six environment variables that define a rectangle by
its top, right, bottom, and left insets from the edge of the viewport. Default value of the keyboard insets are "0px" if a fallback value is not provided else it gets updated when boundingRect
value changes.
The width & height insets are calculated from the remaining insets for developer ergonomics.
The figure and markup below are a representation of a canvas-based spreadsheet that repositions the active cell when the VK is shown. The geometrychange
event triggers a paint request for the canvas. The painting code can then use the boundingRect
property to render the active cell in the proper location.
hide
()
and show
()
methods
hide
()
and show
()
methods to be called in a Secure Context.
show
()
method to be called when sticky activation is present.
boundingRect
, overlaysContent
and ongeometrychange
attributesoverlaysContent
to be set in a secure, top-level browsing context.
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
;
};
partial interface ElementContentEditable
{
[CEReactions] attribute DOMString virtualKeyboardPolicy
;
};
Add contributors
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: