---
title: "On-Screen Keyboard"
slug: "on-screen-keyboard"
updated: 2025-08-11T20:04:39Z
published: 2025-08-11T20:04:39Z
canonical: "docs.developer.comcast.com/on-screen-keyboard"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.developer.comcast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# On-Screen Keyboard

If you need to capture user text input and don’t have your own on-screen keyboard control, the X1 Platform provides a basic soft keyboard for your convenience.

## Lightning app

**Documentation:** [https://rdkcentral.github.io/Lightning-UI-Components/?path=/docs/keyboard--basic](https://rdkcentral.github.io/Lightning-UI-Components/?path=/story/components-keyboard-keyboard--keyboard)

**Source Code**: [https://github.com/rdkcentral/Lightning-UI-Components/tree/master/components/Keyboard](https://github.com/rdkcentral/Lightning-UI-Components/tree/master/components/Keyboard)

## HTML5 app

This keyboard can be embedded in your HTML5 app with a few lines of code. It runs in a separate canvas that overlays the keyboard on your app.

> [!NOTE]
> **Beta product**
> 
> The keyboard control is a beta product. Please use at your discretion.

## Get started

1. Download the keyboard source code: [http://cdn.thor.comcast.com/sdk/keyboard/keyboard-1.0.1-beta.zip](http://cdn.thor.comcast.com/sdk/keyboard/keyboard-1.0.1-beta.zip)
2. Unzip the contents into your html app folder.
3. See `example.html `in the zip file OR follow the usage instructions in this document.

### Examples

In these examples we will provide two ways to integrate the keyboard:

1. Basic usage
2. Advanced usage

Both integrations start with including the library in your app.

Include the following line in the HEAD of of your HTML document (note - change the `src` path to wherever you have downloaded the keyboard):

```plaintext
<script src="js/init-1.0.1-beta.js"></script>
```

### Basic usage

The most basic integration is via adding a data-keyboard to a valid HTML input element:

```plaintext
<input type="text" placeholder="Username" 
       data-keyboard="title:Username;message:Type your username;maxlength:30">
```

After adding the data attribute you only need to add a small script to HTML document:

```plaintext
window.onload = () => {
    const elements = document.querySelectorAll("[data-keyboard]");
    if(elements.length){
        $__OTT_KEYBOARD.attach(elements, "click");
    }
};
```

On window load, we search for all elements with the data-keyboard attribute, and if we find some elements, we attach the keyboard to them and make sure the keyboard will be shown on “click” event. So, you can change the second element to any other valid event to match your need.

The value inside the data attribute is the configuration that will be handed over to the keyboard when it becomes visible via the configured event.

### Advanced usage

The advanced integration provides the option to gain more control over the keyboard output and the way of showing / hiding the keyboard.

This example will use an input element but it’s not required.

First we add an element to the DOM:

```plaintext
<input type="text" placeholder="Click to search" 
       data-title="Find" data-max-length=40 
       data-message="At least 3 characters" id="inputElement">
```

Then we store a reference to the HTML element:

```plaintext
const inputField = document.getElementById("inputElement");
```

Next we reference the actual keyboard:

```plaintext
const keyboard = window.$__OTT_KEYBOARD;
```

and reference the stage (for now the stage will emit the events):

```plaintext
const stage = keyboard.stage;
```

and reference to the canvas (so you can toggle visibility / change position):

```plaintext
const canvas = window.$__OTT_KEYBOARD_CANVAS;
```

Then setup some functions for showing/hiding:

```plaintext
const showKeyboard = () => {
    canvas.style.display = "block";
};

const hideKeyboard = () => {
    canvas.style.display = "none";
};
```

Finally, we add an event listener to the input element which will spawn the keyboard on click, collect the configuration data for the keyboard, and emit a `keyboardConfig` event to the stage (keyboard is listening to `keyboardConfig` event):

```plaintext
inputField.addEventListener("click", () => {
    // grab config from inputfield
    const title = inputField.getAttribute("data-title");
    const message = inputField.getAttribute("data-message");
    const maxlength = inputField.getAttribute("data-max-length");

    // emit changes to stage so keyboard can listen
    // this way you can change title / message per element
    stage.emit("keyboardConfig",{
        title,message, maxlength
    });

    // show keyboard
    showKeyboard();
});
```

### Events

You can listen to the `keyboard change` event. This event will fire after every keypress and the parameter is an object with the properties char (last types char) and value (complete typed value):

```plaintext
stage.on("change", ({char: lastChar, value}) => {
    console.log("keyboard change:", lastChar, value);
});
```

You can listen to the `done` event. This event will click on the done button:

```plaintext
stage.on("done", ({value}) => {
    // first hide keyboard
    hideKeyboard();

    // update input element
    inputField.value = value;
});
```