System Keyboard in WebXR
This guide demonstrates how to use the system keyboard integration in WebXR with Browser to receive text input from users.
WebXR System Keyboard Requirements
Browser version 26.1 or later
WebXR System Keyboard Limitations
There are some limitations in this iteration of the WebXR integration with the Meta Quest headset system keyboard:
- Each time the keyboard is shown represents a new underlying editing session. Any key press first overwrites the entire existing value in the text element.
- The only mechanism for reading keyboard input and interaction is through the text field’s value. At this time, there are no explicit system keyboard key-press events to be intercepted.
- Also consider that for the text field to receive keyboard input, it must be added to the underlying DOM. When appended to an off-screen location, like outside the underlying viewport, the web page scrolls to the text field when the user types. After exiting the immersive session, the page viewport’s contents might be different from what it was when the immersive session was entered.
Sample integration (including source code)
You can run a sample using the integration
here. You can find the implementation in the
source code. The following sections of this guide show relevant portions of the code.
Checking for System Keyboard Support
You can check the isSystemKeyboardSupported
attribute of XRSession
to see if the system keyboard is supported by the UA.
if (session.isSystemKeyboardSupported) {
// ...
}
Showing the System Keyboard
In the Browser, showing the system keyboard is simple and intuitive. It can be used with any HTML text input element.
You can reuse any existing HTML text input element in your document. If you don’t have any, or if you prefer to keep your logic separate, you can create a HTML text input element and append it to the DOM. Just be sure to
remove it at the end of the session.
let myTextField = null; // keep a global reference to read text later
myTextField = document.createElement("input");
myTextField.type = "text";
document.body.appendChild(myTextField);
Then call focus()
on it to trigger the system keyboard.
As the user types into the system keyboard, text populates the element.
To retrieve the text, read the value
property.
var textFromUser = myTextField.value;
Also, an oninput
event listener can respond to any change in the text element’s value as the user is typing.
myTextField.oninput = function() {
// ...
};
System Keyboard Lifecycle
System Keyboard is Displayed The keyboard being displayed triggers an XRSession
visibility state change to visible-blurred
. Add an event listener to respond to it.
Note: Other events can also cause this visibility change.
session.addEventListener('visibilitychange', function(ev) {
if (ev.session.visibilityState === 'visible-blurred') {
// ...
}
});
There are several user interactions that dismiss the keyboard:
- The “hide/dismiss keyboard” button on the keyboard is clicked.
- The Done key on the keyboard is clicked.
- The Meta Quest button on the controller is pressed.
- The user clicks outside of the keyboard bounds.
All of these dismiss the keyboard and result in two events:
- The text field will be blurred.
myTextField.onblur = function() {
// ...
};
- When visibility returns to the session,
XRSession
visibility state changes to visible
.
session.addEventListener('visibilitychange', function(ev) {
if (ev.session.visibilityState === 'visible') {
// ...
}
});
Remove the text input element from the DOM after the XRSession
has ended.
function onSessionEnded(event) {
textField.remove();
}