2018-04-21 04:34:02 +08:00
# simple-keyboard
[](https://www.npmjs.com/package/simple-keyboard)
2018-05-01 03:33:15 +08:00
< a href = "https://franciscohodge.com/projects/simple-keyboard/" > < img src = "https://franciscohodge.com/project-pages/simple-keyboard/images/simple-keyboard.png" align = "center" > < / a >
2018-05-31 11:15:01 +08:00
> The easily customisable and responsive on-screen virtual keyboard for Javascript projects.
2018-04-21 04:34:02 +08:00
2018-07-06 05:20:58 +08:00
< a href = "https://franciscohodge.com/simple-keyboard/demo" title = "View Demo" > < img src = "https://franciscohodge.com/project-pages/simple-keyboard/images/k2.png" align = "center" width = "100%" > < / a >
2018-04-21 04:34:02 +08:00
## Installation
2018-04-24 21:38:14 +08:00
### npm
2018-04-21 04:34:02 +08:00
`npm install simple-keyboard --save`
2018-04-24 21:38:14 +08:00
### zip file (self-hosted)
[Click here to download the latest release (zip format). ](https://github.com/hodgef/simple-keyboard/zipball/master )
2018-07-06 05:24:26 +08:00
> Want to use a CDN instead of self-host? Scroll down to the "Usage with CDN" instructions below.
2018-04-24 21:38:14 +08:00
## Usage with npm
2018-04-21 04:34:02 +08:00
### js
````js
import Keyboard from 'simple-keyboard';
import 'simple-keyboard/build/css/index.css';
2018-05-31 10:28:51 +08:00
let keyboard = new Keyboard({
onChange: input => this.onChange(input),
onKeyPress: button => this.onKeyPress(button)
});
2018-04-24 21:38:14 +08:00
2018-05-31 10:28:51 +08:00
function onChange(input){
document.querySelector(".input").value = input;
console.log("Input changed", input);
2018-04-24 21:38:14 +08:00
}
2018-05-31 10:28:51 +08:00
function onKeyPress(button){
console.log("Button pressed", button);
}
2018-04-21 04:34:02 +08:00
````
### html
````html
2018-05-31 10:28:51 +08:00
< input class = "input" / >
2018-04-21 04:34:02 +08:00
< div class = "simple-keyboard" > < / div >
````
2018-05-31 10:28:51 +08:00
[](https://codesandbox.io/s/krzkx19rr)
2018-04-21 04:34:02 +08:00
> Need a more extensive example? [Click here](https://github.com/hodgef/simple-keyboard/blob/master/src/demo/App.js).
2018-07-06 05:24:26 +08:00
## Usage with CDN
2018-04-24 21:38:14 +08:00
### html
````html
2018-05-31 10:28:51 +08:00
< html >
2018-04-24 21:38:14 +08:00
< head >
2018-07-14 05:23:28 +08:00
< link rel = "stylesheet" href = "https://cdn.jsdelivr.net/npm/simple-keyboard@latest/build/css/index.css" >
2018-04-24 21:38:14 +08:00
< / head >
2018-05-31 10:28:51 +08:00
2018-04-24 21:38:14 +08:00
< body >
2018-05-31 10:28:51 +08:00
< input class = "input" placeholder = "Tap on the virtual keyboard to start" / >
< div class = "simple-keyboard" > < / div >
2018-07-14 05:23:28 +08:00
< script src = "https://cdn.jsdelivr.net/npm/simple-keyboard@latest/build/index.min.js" > < / script >
2018-05-31 10:28:51 +08:00
< script src = "src/index.js" > < / script >
2018-04-24 21:38:14 +08:00
< / body >
2018-05-31 10:28:51 +08:00
2018-04-24 21:38:14 +08:00
< / html >
````
2018-05-31 10:28:51 +08:00
### js (index.js)
````js
2018-06-08 22:39:20 +08:00
let Keyboard = window.SimpleKeyboard.default;
let myKeyboard = new Keyboard({
onChange: input => onChange(input),
onKeyPress: button => onKeyPress(button)
2018-05-31 10:28:51 +08:00
});
2018-06-08 22:39:20 +08:00
function onChange(input) {
document.querySelector(".input").value = input;
console.log("Input changed", input);
}
function onKeyPress(button) {
console.log("Button pressed", button);
}
2018-05-31 10:28:51 +08:00
````
[](https://codesandbox.io/s/6n0wzxjmjk)
2018-04-21 04:34:02 +08:00
## 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
```js
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}'
]
}
```
### layoutName
> Specifies which layout should be used.
```js
layoutName: "default"
```
### display
> Replaces variable buttons (such as `{bksp}`) with a human-friendly name (e.g.: "delete").
```js
display: {
'{bksp}': 'delete',
'{enter}': '< enter ' ,
'{shift}': 'shift',
'{s}': 'shift',
'{tab}': 'tab',
'{lock}': 'caps',
'{accept}': 'Submit',
'{space}': ' ',
'{//}': ' '
}
```
### theme
2018-06-30 09:43:22 +08:00
> A prop to add your own css classes _to the keyboard wrapper_. You can add multiple classes separated by a space.
2018-04-21 04:34:02 +08:00
```js
theme: "hg-theme-default"
```
2018-06-30 09:43:22 +08:00
### buttonTheme
> A prop to add your own css classes _to one or several buttons_. You can add multiple classes separated by a space.
```js
buttonTheme: [
{
class: "myCustomClass",
buttons: "Q W E R T Y q w e r t y"
},
{
class: "anotherCustomClass",
buttons: "Q q"
},
...
]
```
[](https://codesandbox.io/s/vj8jvz2q4l?module=%2Fsrc%2Findex.js)
2018-04-21 04:34:02 +08:00
### debug
> Runs a console.log every time a key is pressed. Displays the buttons pressed and the current input.
```js
debug: false
```
### newLineOnEnter
> Specifies whether clicking the "ENTER" button will input a newline (`\n`) or not.
```js
newLineOnEnter: false
```
2018-04-30 23:05:55 +08:00
### inputName
> Allows you to use a single simple-keyboard instance for several inputs.
```js
inputName: "default"
```
2018-05-01 00:47:18 +08:00
### onKeyPress
> Executes the callback function on key press. Returns button layout name (i.e.: "{shift}").
```js
onKeyPress: (button) => console.log(button)
```
### onChange
> Executes the callback function on input change. Returns the current input's string.
```js
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](#using-several-inputs)*" guide.
```js
onChangeAll: (inputs) => console.log(inputs)
```
2018-04-21 04:34:02 +08:00
## Methods
2018-04-24 21:38:14 +08:00
simple-keyboard has a few methods you can use to further control it's behavior.
2018-04-21 04:34:02 +08:00
To access these functions, you need the instance the simple-keyboard component, like so:
```js
var keyboard = new Keyboard({
...
});
/>
// Then, use as follows...
keyboard.methodName(params);
```
### clearInput
> Clear the keyboard's input.
```js
2018-05-01 00:47:18 +08:00
// For default input (i.e. if you have only one)
2018-04-21 04:34:02 +08:00
keyboard.clearInput();
2018-05-01 00:47:18 +08:00
// For specific input
// Must have been previously set using the "inputName" prop.
keyboard.clearInput("inputName");
2018-04-21 04:34:02 +08:00
```
### getInput
> Get the keyboard's input (You can also get it from the _onChange_ prop).
```js
2018-05-01 00:47:18 +08:00
// For default input (i.e. if you have only one)
2018-04-21 04:34:02 +08:00
let input = keyboard.getInput();
2018-05-01 00:47:18 +08:00
// For specific input
// Must have been previously set using the "inputName" prop.
let input = keyboard.getInput("inputName");
2018-04-21 04:34:02 +08:00
```
### setInput
2018-07-04 07:10:47 +08:00
> Set the keyboard's input. Useful if you want to track input changes made outside simple-keyboard.
2018-04-21 04:34:02 +08:00
```js
2018-05-01 00:47:18 +08:00
// For default input (i.e. if you have only one)
2018-04-21 04:34:02 +08:00
keyboard.setInput("Hello World!");
2018-05-01 00:47:18 +08:00
// For specific input
// Must have been previously set using the "inputName" prop.
keyboard.setInput("Hello World!", "inputName");
2018-04-21 04:34:02 +08:00
```
2018-04-30 23:05:55 +08:00
### setOptions
> Set new option or modify existing ones after initialization. The changes are applied immediately.
```js
keyboard.setOptions({
theme: "my-custom-theme"
});
```
## Use-cases
### Using several inputs
Set the *[inputName](#inputname)* option for each input you want to handle with simple-keyboard.
For example:
2018-05-03 00:41:29 +08:00
2018-04-30 23:05:55 +08:00
```html
< input class = "input" id = "input1" value = "" / >
< input class = "input" id = "input2" value = "" / >
```
```js
2018-05-03 00:41:29 +08:00
// Here we'll store the input id that simple-keyboard will be using.
var selectedInput;
2018-04-30 23:05:55 +08:00
// Initialize simple-keyboard as usual
var keyboard = new Keyboard({
2018-05-03 00:41:29 +08:00
onChange: input => onChange(input)
2018-04-30 23:05:55 +08:00
});
// Add an event listener for the inputs to be tracked
document.querySelectorAll('.input')
.forEach(input => input.addEventListener('focus', onInputFocus));
2018-05-03 00:41:29 +08:00
/**
* 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 !
2018-04-30 23:05:55 +08:00
keyboard.setOptions({
inputName: event.target.id
});
}
2018-05-03 00:41:29 +08:00
// 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;
}
2018-04-30 23:05:55 +08:00
```
2018-05-03 00:41:29 +08:00
2018-05-01 00:47:18 +08:00
> [See full example](https://github.com/hodgef/simple-keyboard/blob/master/src/demo/MultipleInputsDemo.js).
2018-04-30 23:05:55 +08:00
2018-07-04 07:10:47 +08:00
[](https://codesandbox.io/s/43nm6v4xyx?module=%2Fsrc%2Findex.js)
2018-04-21 04:34:02 +08:00
## Demo
[https://franciscohodge.com/simple-keyboard/demo ](https://franciscohodge.com/simple-keyboard/demo )
2018-05-31 10:28:51 +08:00
[](https://codesandbox.io/s/krzkx19rr)
2018-04-21 04:34:02 +08:00
### To run demo on your own computer
* Clone this repository
* `npm install`
* `npm start`
* Visit [http://localhost:3000/ ](http://localhost:3000/ )
2018-06-08 22:59:11 +08:00
### Other versions
2018-04-21 04:34:02 +08:00
2018-06-08 22:59:11 +08:00
* ReactJS - [react-simple-keyboard ](https://github.com/hodgef/react-simple-keyboard )
## Contributing
PR's and issues are welcome. Feel free to submit any issues you have at:
2018-04-21 04:34:02 +08:00
[https://github.com/hodgef/simple-keyboard/issues ](https://github.com/hodgef/simple-keyboard/issues )
