Documentation for the VirtualKeyboard API

files/en-us/web/api/navigator/index.md

@@ -79,6 +79,8 @@ _Doesn't inherit any properties._
   - : Returns the user agent string for the current browser.
 - {{domxref("Navigator.userAgentData")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : Returns a {{domxref("NavigatorUAData")}} object, which gives access to information about the browser and operating system of the user.
+- {{domxref("Navigator.virtualKeyboard")}} {{ReadOnlyInline}}
+  - : Returns a reference to the {{domxref("VirtualKeyboard")}} API, to take control of the on-screen virtual keyboard.
 - {{domxref("Navigator.webdriver")}} {{ReadOnlyInline}}
   - : Indicates whether the user agent is controlled by automation.
 - {{domxref("Navigator.windowControlsOverlay")}} {{ReadOnlyInline}}

files/en-us/web/api/navigator/virtualkeyboard/index.md

@@ -0,0 +1,32 @@
+---
+title: Navigator.virtualKeyboard
+slug: Web/API/Navigator/virtualKeyboard
+page-type: web-api-instance-property
+tags:
+  - API
+  - Navigator
+  - Property
+  - Reference
+  - Experimental
+  - VirtualKeyboard
+browser-compat: api.Navigator.virtualKeyboard
+---
+
+{{APIRef("VirtualKeyboard")}}
+
+The **`virtualKeyboard`** read-only property
+of the {{domxref("navigator")}} interface returns a reference to the {{domxref("VirtualKeyboard")}} instance object.
+
+The {{domxref("VirtualKeyboard_API", "VirtualKeyboard API", "", "nocode")}} gives developers control over the layout of their applications when the on-screen virtual keyboard appears and disappears on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available.
+
+## Value
+
+A {{domxref("VirtualKeyboard")}} object you can use to opt-out of the automatic virtual keyboard behavior, show or hide the virtual keyboard programmatically, and get the current position and size of the virtual keyboard.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/virtualkeyboard/boundingrect/index.md

@@ -0,0 +1,42 @@
+---
+title: VirtualKeyboard.boundingRect
+slug: Web/API/VirtualKeyboard/boundingRect
+page-type: web-api-instance-property
+tags:
+  - API
+  - Property
+  - Reference
+  - VirtualKeyboard
+  - boundingRect
+  - Experimental
+browser-compat: api.VirtualKeyboard.boundingRect
+---
+
+{{APIRef("VirtualKeyboard API")}}{{SeeCompatTable}}
+
+The **`boundingRect`** property of the {{domxref("VirtualKeyboard")}} interface contains a {{domxref("DOMRect")}} indicating the position and size of the on-screen virtual keyboard that overlays the web page.
+
+The on-screen virtual keyboard will overlay the viewport when the {{domxref("VirtualKeyboard_API", "Virtual Keyboard API", "", "nocode")}} is used to prevent the browser from resizing the viewport automatically. This is done by setting the {{domxref("VirtualKeyboard.overlaysContent", "overlaysContent")}} property to `true`.
+
+## Value
+
+A {{domxref("DOMRect")}} which indicates the position and size of the virtual keyboard in the viewport.
+
+The `x`, `y`, `width`, and `height` coordinates of the rectangle are useful to reposition content in the webpage that needs to be visible even when the virtual keyboard is displayed.
+
+```js
+const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("VirtualKeyboard_API", "The VirtualKeyboard API", "", "nocode")}}
+- [Full control with the VirtualKeyboard API](https://developer.chrome.com/docs/web-platform/virtual-keyboard/)

files/en-us/web/api/virtualkeyboard/geometrychange_event/index.md

@@ -0,0 +1,61 @@
+---
+title: 'VirtualKeyboard: geometrychange event'
+slug: Web/API/VirtualKeyboard/geometrychange_event
+page-type: web-api-event
+tags:
+  - API
+  - Event
+  - Reference
+  - VirtualKeyboard
+  - geometrychange
+  - Experimental
+browser-compat: api.VirtualKeyboard.geometrychange_event
+---
+
+{{APIRef("VirtualKeyboard API")}}{{SeeCompatTable}}
+
+The **`geometrychange`** event of the {{domxref("VirtualKeyboard")}}
+interface fires when the on-screen virtual keyboard is toggled between shown and hidden states.
+
+The `geometrychange` event is useful to detect when the virtual keyboard appears and disappears, so you can adjust the layout as appropriate. This is necessary when using the {{domxref("VirtualKeyboard_API", "Virtual Keyboard API", "", "nocode")}} to disable the browser's default automatic resizing of the viewport when the virtual keyboard is shown and hidden.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+navigator.virtualKeyboard.addEventListener('geometrychange', (event) => { });
+
+navigator.virtualKeyboard.ongemoetrychange = (event) => { };
+```
+
+## Event type
+
+A generic {{domxref("Event")}}.
+
+## Examples
+
+The following code snippet uses the `geometrychange` event to detect when the virtual keyboard geometry changes, and then accesses the {{domxref("VirtualKeyboard.boundingRect", "boundingRect")}} property to query the size and position of the virtual keyboard:
+
+```js
+if("virtualKeyboard" in navigator) {
+  navigator.overlaysContent = true;
+
+  navigator.virtualKeyboard.addEventListener("geometrychange", event => {
+    const { x, y, width, height } = event.target.boundingRect;
+  });
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("VirtualKeyboard_API", "The VirtualKeyboard API", "", "nocode")}}
+- [Full control with the VirtualKeyboard API](https://developer.chrome.com/docs/web-platform/virtual-keyboard/)

files/en-us/web/api/virtualkeyboard/hide/index.md

@@ -0,0 +1,77 @@
+---
+title: VirtualKeyboard.hide()
+slug: Web/API/VirtualKeyboard/hide
+page-type: web-api-instance-method
+tags:
+  - API
+  - Method
+  - Reference
+  - VirtualKeyboard
+  - hide
+  - Experimental
+browser-compat: api.VirtualKeyboard.hide
+---
+
+{{APIRef("VirtualKeyboard API")}}{{SeeCompatTable}}
+
+The **`hide()`** method of the {{domxref("VirtualKeyboard")}} interface programmatically hides the on-screen virtual keyboard. This is useful when the page needs to implement its own virtual keyboard logic by using the {{domxref("VirtualKeyboard_API", "VirtualKeyboard API", "", "nocode")}}.
+
+This method only works if the currently-focused element is a form control — such as an {{htmlelement("input")}} or {{htmlelement("textarea")}} element — or if the focused element is {{htmlattrxref("contenteditable")}}.
+
+The `hide()` method always returns `undefined` and triggers a {{domxref("VirtualKeyboard.geometrychange_event", "geometrychange")}} event.
+
+## Syntax
+
+```js-nolint
+hide()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+Undefined.
+
+## Example
+
+The code snippet below shows how to use the `virtualkeyboardpolicy` attribute to prevent the browser from showing the virtual keyboard on click or tap. The code also uses the `navigator.virtualKeyboard.show()` and `navigator.virtualKeyboard.hide()` methods to show and hide the virtual keyboard when a button is clicked:
+
+```js
+<div contenteditable virtualkeyboardpolicy="manual" id="editor"></div>
+<button id="edit-button">Edit</button>
+<script>
+  if ("virtualKeyboard" in navigator) {
+    const editor = document.getElementById("editor");
+    const editButton = document.getElementById("edit-button");
+    let isEditing = false;
+
+    editButton.addEventListener("click", () => {
+      if (isEditing) {
+        navigator.virtualKeyboard.hide();
+        editButton.textContent = "Edit";
+      } else {
+        editor.focus();
+        navigator.virtualKeyboard.show();
+        editButton.textContent = "Save changes";
+      }
+
+      isEditing = !isEditing;
+    });
+  }
+</script>
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("VirtualKeyboard_API", "The VirtualKeyboard API", "", "nocode")}}
+- [Full control with the VirtualKeyboard API](https://developer.chrome.com/docs/web-platform/virtual-keyboard/)

files/en-us/web/api/virtualkeyboard/index.md

@@ -0,0 +1,73 @@
+---
+title: VirtualKeyboard
+slug: Web/API/VirtualKeyboard
+page-type: web-api-interface
+tags:
+  - API
+  - Experimental
+  - Interface
+  - VirtualKeyboard API
+  - Reference
+  - keyboard
+browser-compat: api.VirtualKeyboard
+---
+
+{{SeeCompatTable}}{{APIRef("VirtualKeyboard API")}}
+
+The **`VirtualKeyboard`** interface of the [VirtualKeyboard API](/en-US/docs/Web/API/VirtualKeyboard_API) is useful on devices that have on-screen virtual keyboards, such as tablets, mobile phones, or other devices where a hardware keyboard may not be available.
+
+The `VirtualKeyboard` interface makes it possible to opt out of the automatic way browsers handle on-screen virtual keyboards by reducing the height of the viewport to make room for the virtual keyboard. You can prevent the browser from changing the size of the viewport, detect the position and size of the virtual keyboard — adapting the layout of your web page as a follow-up — and programmatically show or hide the virtual keyboard.
+
+You access the `VirtualKeyboard` interface by using {{domxref("navigator.virtualKeyboard")}}.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+_The `VirtualKeyboard` interface doesn't inherit any properties._
+
+- {{DOMxRef("VirtualKeyboard.boundingRect")}} {{ReadOnlyInline}}
+  - : A {{domxref("DOMRect")}} that describes the geometry of the virtual keyboard.
+- {{DOMxRef("VirtualKeyboard.overlaysContent")}}
+  - : A {{jsxref('Boolean')}} that defines whether the browser should stop handling the on-screen virtual keyboard.
+
+### Events
+
+- {{domxref("VirtualKeyboard.geometrychange_event", "geometrychange")}}
+  - : Fires when the geometry of the on-screen virtual keyboard changes, which happens when the virtual keyboard appears or disappears.
+
+## Instance methods
+
+_The `VirtualKeyboard` interface doesn't inherit any methods_.
+
+- {{domxref('VirtualKeyboard.show()')}} {{experimental_inline}}
+  - : Show the virtual keyboard.
+- {{domxref('VirtualKeyboard.hide()')}} {{experimental_inline}}
+  - : Hide the virtual keyboard.
+
+## Example
+
+The following example demonstrates how to opt out of the automatic virtual keyboard behavior, and detect the geometry of the virtual keyboard in the web page:
+
+```js
+if("virtualKeyboard" in navigator) {
+  navigator.overlaysContent = true;
+
+  navigator.virtualKeyboard.addEventListener("geometrychange", event => {
+    const { x, y, width, height } = event.target.boundingRect;
+  });
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("VirtualKeyboard_API", "The VirtualKeyboard API", "", "nocode")}}
+- [Full control with the VirtualKeyboard API](https://developer.chrome.com/docs/web-platform/virtual-keyboard/)

files/en-us/web/api/virtualkeyboard/overlayscontent/index.md

@@ -0,0 +1,45 @@
+---
+title: VirtualKeyboard.overlaysContent
+slug: Web/API/VirtualKeyboard/overlaysContent
+page-type: web-api-instance-property
+tags:
+  - API
+  - Property
+  - Reference
+  - VirtualKeyboard
+  - overlaysContent
+  - Experimental
+browser-compat: api.VirtualKeyboard.overlaysContent
+---
+
+{{APIRef("VirtualKeyboard API")}}{{SeeCompatTable}}
+
+The **`overlaysContent`** property of the VirtualKeyboard interface can be used to opt out of the automatic way in which browsers handle on-screen virtual keyboards by reducing the size of the viewport to make space for them.
+
+If the `overlaysContent` property is set to `true`, the browser no longer resizes the viewport when the virtual keyboard appears. The virtual keyboard instead overlays the content of the web page, and you can adapt the page layout as appropriate using the {{domxref("VirtualKeyboard_API", "Virtual Keyboard API", "", "nocode")}} and your own custom CSS and JavaScript.
+
+## Value
+
+A boolean. `false` by default, set it to `true` to opt out of the browser's automatic handling of the on-screen virtual keyboard.
+
+## Example
+
+```js
+if ("virtualKeyboard" in navigator) {
+  console.log(navigator.virtualKeyboard.overlaysContent); // false
+  navigator.virtualKeyboard.overlaysContent = true; // Opt out of the automatic handling.
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("VirtualKeyboard_API", "The VirtualKeyboard API", "", "nocode")}}
+- [Full control with the VirtualKeyboard API](https://developer.chrome.com/docs/web-platform/virtual-keyboard/)