| bin | ||
| build | ||
| config | ||
| public | ||
| scripts | ||
| src | ||
| .gitignore | ||
| .npmignore | ||
| .travis.yml | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
The easily customisable and responsive on-screen virtual keyboard for Javascript projects.
Installation
npm
npm install simple-keyboard --save
zip file (self-hosted)
Click here to download the latest release (zip format).
Want to use a CDN instead of self-host? Scroll down to the "Usage with CDN" instructions below.
Usage with npm
js
import Keyboard from 'simple-keyboard';
import 'simple-keyboard/build/css/index.css';
let keyboard = new Keyboard({
onChange: input => onChange(input),
onKeyPress: button => onKeyPress(button)
});
function onChange(input){
document.querySelector(".input").value = input;
console.log("Input changed", input);
}
function onKeyPress(button){
console.log("Button pressed", button);
}
html
<input class="input" />
<div class="simple-keyboard"></div>
Need a more extensive example? Click here.
Usage with CDN
html
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/simple-keyboard@latest/build/css/index.css">
</head>
<body>
<input class="input" placeholder="Tap on the virtual keyboard to start" />
<div class="simple-keyboard"></div>
<script src="https://cdn.jsdelivr.net/npm/simple-keyboard@latest/build/index.min.js"></script>
<script src="src/index.js"></script>
</body>
</html>
js (index.js)
let Keyboard = window.SimpleKeyboard.default;
let myKeyboard = new Keyboard({
onChange: input => onChange(input),
onKeyPress: button => onKeyPress(button)
});
function onChange(input) {
document.querySelector(".input").value = input;
console.log("Input changed", input);
}
function onKeyPress(button) {
console.log("Button pressed", button);
}
Options
You can customize the Keyboard by passing options to it. Here are the available options (the code examples are the defaults):
layout
Modify the keyboard layout
layout: {
'default': [
'` 1 2 3 4 5 6 7 8 9 0 - = {bksp}',
'{tab} q w e r t y u i o p [ ] \\',
'{lock} a s d f g h j k l ; \' {enter}',
'{shift} z x c v b n m , . / {shift}',
'.com @ {space}'
],
'shift': [
'~ ! @ # $ % ^ & * ( ) _ + {bksp}',
'{tab} Q W E R T Y U I O P { } |',
'{lock} A S D F G H J K L : " {enter}',
'{shift} Z X C V B N M < > ? {shift}',
'.com @ {space}'
]
}
Looking for keyboard layouts in other languages? Check out simple-keyboard-layouts !
layoutName
Specifies which layout should be used.
layoutName: "default"
display
Replaces variable buttons (such as
{bksp}) with a human-friendly name (e.g.: "backspace").
display: {
'{bksp}': 'backspace',
'{enter}': '< enter',
'{shift}': 'shift',
'{s}': 'shift',
'{tab}': 'tab',
'{lock}': 'caps',
'{accept}': 'Submit',
'{space}': ' ',
'{//}': ' '
}
theme
A prop to add your own css classes to the keyboard wrapper. You can add multiple classes separated by a space.
theme: "hg-theme-default"
buttonTheme
A prop to add your own css classes to one or several buttons. You can add multiple classes separated by a space.
buttonTheme: [
{
class: "myCustomClass",
buttons: "Q W E R T Y q w e r t y"
},
{
class: "anotherCustomClass",
buttons: "Q q"
},
...
]
debug
Runs a console.log every time a key is pressed. Displays the buttons pressed and the current input.
debug: false
newLineOnEnter
Specifies whether clicking the "ENTER" button will input a newline (
\n) or not.
newLineOnEnter: false
inputName
Allows you to use a single simple-keyboard instance for several inputs.
inputName: "default"
onKeyPress
Executes the callback function on key press. Returns button layout name (i.e.: "{shift}").
onKeyPress: (button) => console.log(button)
onChange
Executes the callback function on input change. Returns the current input's string.
onChange: (input) => console.log(input)
onChangeAll
Executes the callback function on input change. Returns the input object with all defined inputs. This is useful if you're handling several inputs with simple-keyboard, as specified in the "Using several inputs" guide.
onChangeAll: (inputs) => console.log(inputs)
Methods
simple-keyboard has a few methods you can use to further control it's behavior. To access these functions, you need the instance the simple-keyboard component, like so:
var keyboard = new Keyboard({
...
});
/>
// Then, use as follows...
keyboard.methodName(params);
clearInput
Clear the keyboard's input.
// For default input (i.e. if you have only one)
keyboard.clearInput();
// For specific input
// Must have been previously set using the "inputName" prop.
keyboard.clearInput("inputName");
getInput
Get the keyboard's input (You can also get it from the onChange prop).
// For default input (i.e. if you have only one)
let input = keyboard.getInput();
// For specific input
// Must have been previously set using the "inputName" prop.
let input = keyboard.getInput("inputName");
setInput
Set the keyboard's input. Useful if you want to track input changes made outside simple-keyboard.
// For default input (i.e. if you have only one)
keyboard.setInput("Hello World!");
// For specific input
// Must have been previously set using the "inputName" prop.
keyboard.setInput("Hello World!", "inputName");
setOptions
Set new option or modify existing ones after initialization. The changes are applied immediately.
keyboard.setOptions({
theme: "my-custom-theme"
});
Use-cases
Using several inputs
Set the inputName option for each input you want to handle with simple-keyboard.
For example:
<input class="input" id="input1" value=""/>
<input class="input" id="input2" value=""/>
// Here we'll store the input id that simple-keyboard will be using.
var selectedInput;
// Initialize simple-keyboard as usual
var keyboard = new Keyboard({
onChange: input => onChange(input)
});
// Add an event listener for the inputs to be tracked
document.querySelectorAll('.input')
.forEach(input => input.addEventListener('focus', onInputFocus));
/**
* When an input is focused, it will be marked as selected (selectedInput)
* This is so we can replace it's value on the onChange function
*
* Also, we will set the inputName option to a unique string identifying the input (id)
* simple-keyboard save the input in this key and report changes through onChange
*/
onInputFocus = event => {
// Setting input as selected
selectedInput = `#${event.target.id}`;
// Set the inputName option on the fly !
keyboard.setOptions({
inputName: event.target.id
});
}
// When the current input is changed, this is called
onChange = input => {
// If the input is not defined, grabbing the first ".input".
let currentInput = selectedInput || '.input';
// Updating the selected input's value
document.querySelector(currentInput).value = input;
}
Having keys in a different language configuration
There's a number of key layouts available. To apply them, check out simple-keyboard-layouts.
If you'd like to contribute your own layouts, please submit your pull request at the simple-keyboard-layouts repository.
Demo
https://franciscohodge.com/simple-keyboard/demo
To run demo on your own computer
- Clone this repository
npm installnpm start- Visit http://localhost:3000/
Other versions
- ReactJS - react-simple-keyboard
Contributing
PR's and issues are welcome. Feel free to submit any issues you have at: https://github.com/hodgef/simple-keyboard/issues