VirtualKeyboard API

Abstract

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.

3. The `VirtualKeyboard` Interface

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:

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:

Let window be this's relevant global object. Assert that window is a Window object.
If window does not have sticky activation, abort these steps.
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.
If the virtualKeyboardPolicy is not manual or inputMode's attribute value is none then abort these steps.
Call the system API to show the VK.
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:

Let window be this's relevant global object. Assert that window is a Window object.
If window does not have sticky activation, abort these steps.
If the focused element's virtualKeyboardPolicy is not manual or inputMode's attribute value is none then abort these steps.
Call the system API to hide the VK.
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:

Let osk be the on-screen keyboard rectangle that is the result of running the algorithm in show() or hide() on this.
Let lv be the document's viewport that is the result of running the algorithm in show() or hide() on this.
Map osk to the coordinate space of lv.
Let bounds be a DOMRect object.
Update bounds by intersecting lv with the osk.
Map bounds to the coordinate space of lv.
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.

4. Extensions to the `ElementContentEditable` mixin

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

Issue 1

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.

Issue 2

Specify timing relative to events like focus.

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.

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

6. Examples

6.1 Example with usage of VK control APIs.

Example 1: VirtualKeyboardPolicy


<div contenteditable virtualkeyboardpolicy="manual" inputmode="text"
style="height:50px;width:300px;border:1px solid black;"data-formula="12+30">42</div>
<script>
    let div = document.querySelector("div")
    div.addEventListener("focusout", handleFocusOut)
    div.addEventListener("dblclick", handleDblClick)

    function handleFocusOut() {
        let formula = parseIntoFormula(div.firstChild.data)
        div.setAttribute("data-formula", formula)
        div.firstChild.data = evaluateFormula(formula)
    }

    function handleDblClick(e) {
        div.firstChild.data = div.getAttribute("data-formula")

        if (e.pointerType == "touch") {
            navigator.virtualKeyboard.show()
        }
    }

    function parseIntoFormula(text) {
        return "12+30"
    }

    function evaluateFormula(formula) {
        return "42"
    }

    function handleSuccessfulShow() {
        // handle success of VK shown
    }

    function handleFailedShow() {
        // handle failure of VK shown
    }
</script>

6.2 Examples with usage of overlaysContent and geometry event as a result of VK showing.

Example 2: Repositioning Content using CSS with overlaysContent


    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        body {
            display: grid;
            margin: 8px;
            height: calc(100vh - 16px);
            grid-template:
            "messages"  1fr
            "input"     auto
            "keyboard"  env(keyboard-inset-height, 0px);
        }
        input[type=text]::placeholder {
            color: #444;
        }
        input[type=text] {
            padding: 10px;
            font-size: 24px;
            border: 4px solid black;
            border-radius: 4px;
            background-color: #86DBF6;
            justify-self: center;
        }
    </style>
    <div id="messages">...</div>
    <input type="text" placeholder="type...">
    <script>
        if ("virtualKeyboard" in navigator) {
            navigator.virtualKeyboard.overlaysContent = true
        }
    </script>

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. Figure showing virtual keyboard on single-touch screen device

Example 3: Repositioning Content using JavaScript geometrychange


    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        body {
            display: grid;
            margin: 0;
            height: 100vh;
            grid-template:
            "controls" min-content
            "cells"    1fr;
        }
        #controls {
            height: 100px;
            background-color: #139CFF;
        }
        canvas {
            justify-self: stretch;
            align-self: stretch;
        }
    </style>
    <div id="controls">...</div>
    <canvas></canvas>
    <script type="module">
        navigator.virtualKeyboard.overlaysContent = true

        navigator.virtualKeyboard.addEventListener("geometrychange", () => {
            // Request the canvas be repainted so it can reposition
            // the active cell above the virtual keyboard.
            requestAnimationFrame(paintCanvas)
        })

        paintCanvas() {
            let keyboardRect = navigator.virtualKeyboard.boundingRect
            // Use keyboard rect in omitted code below to paint cells in the
            // proper position accounting for the keyboard rect along with
            // any panning of the cell area that the user may have performed.
        }
    </script>

The figure below represents a map application that presents a map on one window segment and search results on another. Using the proposal for Window Segments and media queries, the search box shown will increase its bottom margin to remain visible whenever the virtual keyboard appears on the left side of the foldable device. Figure showing virtual keyboard on single-touch screen device

Figure showing virtual keyboard on single-touch screen device

Example 4: Repositioning Content on Foldable Devices with overlaysContent


    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        @media (spanning: single-fold-vertical) {
            body {
                display: grid;
                margin: 0;
                height: 100vh;
                grid-template-columns: env(fold-left) calc(100vw - env(fold-right));
                grid-column-gap: calc(env(fold-right) - env(fold-left));
            }
            .map {
                grid-column: 1;
                grid-row: 1;
            }
            .search-box {
            /* overlay into same grid column as the map */
                grid-column: 1;
                grid-row: 1;

                /* position the search box at the bottom of the cell, centered */
                align-self: end;

                /* margin when keyboard not showing on left screen */
                margin: 20px;

                /* give it a little style */
                padding: 10px;
                font-size: 24px;
                border: 4px solid black;
                border-radius: 4px;
                background-color: #86DBF6;
            }
            .locations-list {
                grid-column: 2;
                grid-row: 1;
            }

            @media (env(keyboard-inset-right) <= env(fold-left)) {
            /* keyboard is on the left screen, adjust search box */
                .search-box {
                    margin-bottom: calc(20px + env(keyboard-inset-height));
                }
            }
        }
    </style>
    <div class="map">...</div>
    <input class="search-box" type="search" placeholder="search...">
    <div class="locations-list">...</div>
    <script type="module">
        navigator.virtualKeyboard.overlaysContent = true
    </script>

7. Privacy and Security Considerations

Because VirtualKeyboard APIs may reveal some aspects about layout of user's VK, user agents must ensure that no extra information is exposed to the script that it already has through existing APIs. To mitigate potential security and privacy risks, browsers are expected to follow best practices described below.

7.1 `hide()` and `show()` methods

User Agent MUST only allow hide() and show() methods to be called in a Secure Context.
User Agent MUST only allow the show() method to be called when sticky activation is present.

7.2 `boundingRect`, `overlaysContent` and `ongeometrychange` attributes

User Agent MUST only allow overlaysContent to be set in a secure, top-level browsing context.

VirtualKeyboard API

W3C First Public Working Draft 24 August 2021

Abstract

Status of This Document

1. Introduction

2. Conformance

3. The `VirtualKeyboard` Interface

4. Extensions to the `ElementContentEditable` mixin

5. Virtual Keyboard Visibility Change CSS environment variables.

5.1 Keyboard inset variables

6. Examples

6.1 Example with usage of VK control APIs.

6.2 Examples with usage of overlaysContent and geometry event as a result of VK showing.

7. Privacy and Security Considerations

7.1 `hide()` and `show()` methods

7.2 `boundingRect`, `overlaysContent` and `ongeometrychange` attributes

A. IDL Index

B. Contributors

C. References

C.1 Normative references

VirtualKeyboard API

W3C First Public Working Draft 24 August 2021

Abstract

Status of This Document

1. Introduction

2. Conformance

3. The VirtualKeyboard Interface

4. Extensions to the ElementContentEditable mixin

5. Virtual Keyboard Visibility Change CSS environment variables.

5.1 Keyboard inset variables

6. Examples

6.1 Example with usage of VK control APIs.

6.2 Examples with usage of overlaysContent and geometry event as a result of VK showing.

7. Privacy and Security Considerations

7.1 hide() and show() methods

7.2 boundingRect, overlaysContent and ongeometrychange attributes

A. IDL Index

B. Contributors

C. References

C.1 Normative references

3. The `VirtualKeyboard` Interface

4. Extensions to the `ElementContentEditable` mixin

7.1 `hide()` and `show()` methods

7.2 `boundingRect`, `overlaysContent` and `ongeometrychange` attributes