react-simple-keyboard

The easily customisable and responsive on-screen virtual keyboard, now for React.js projects.

Want the vanilla js version? Get simple-keyboard instead!

Installation

npm install react-simple-keyboard --save

Usage

import React, {Component} from 'react';
import Keyboard from 'react-simple-keyboard';
import 'simple-keyboard/build/css/index.css';

class App extends Component {

  onChange = (input) => {
    console.log("Input changed", input);
  }

  onKeyPress = (button) => {
    console.log("Button pressed", button);
  }

  render(){
    return (
      <Keyboard
        onChange={input =>
          this.onChange(input)}
        onKeyPress={button =>
          this.onKeyPress(button)}
      />
    );
  }
}

export default App;

Need a more extensive example? Click here.

Options

You can customize the Keyboard by passing options (props) 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.: "delete").

display={{
  '{bksp}': 'delete',
  '{enter}': '< enter',
  '{shift}': 'shift',
  '{s}': 'shift',
  '{tab}': 'tab',
  '{lock}': 'caps',
  '{accept}': 'Submit',
  '{space}': ' ',
  '{//}': ' '
}}

theme

A prop to add your own css classes. 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"}

baseClass

Sets a personalized unique id (base class) for your simple-keyboard instance. This is useful if you want to have many simple-keyboard instances and do not want to confuse them.

If not set, a random baseClass will be used (e.g.: simplekeyboard_id-qeu5wu to differentiate your instance from others you may spawn).

baseClass={"myBaseClass"}

syncInstanceInputs

When set to true, this option synchronizes the internal input of every simple-keyboard instance.

syncInstanceInputs={false}

physicalKeyboardHighlight

When set to true, this option adds the special class (hg-selectedButton) to the key that matches. For example, when you press the a key, that key in simple-keyboard will have the special class until the key is released.

For functional keys such as shift, note that the key's event.code is used. In that instance, pressing the left key will result in the code ShiftLeft. Therefore, the key must be named {shiftleft}. Click here for some of keys supported out of the box.

If in doubt, you can also set the debug option to true.

physicalKeyboardHighlight={true}

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 a ref of the simple-keyboard component, like so:

<Keyboard
  ref={r => this.keyboard = r}
  [...]
/>

// Then, on componentDidMount ..
this.keyboard.methodName(params);

clearInput

Clear the keyboard's input.

// For default input (i.e. if you have only one)
this.keyboard.clearInput();

// For specific input
// Must have been previously set using the "inputName" prop.
this.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 = this.keyboard.getInput();

// For specific input
// Must have been previously set using the "inputName" prop.
let input = this.keyboard.getInput("inputName");

setInput

Set the keyboard's input. Useful if you want the keybord to initialize with a default value, for example.

// For default input (i.e. if you have only one)
this.keyboard.setInput("Hello World!");

// For specific input
// Must have been previously set using the "inputName" prop.
this.keyboard.setInput("Hello World!", "inputName");

It returns a promise, so if you want to run something after it's applied, call it as so:

let inputSetPromise = this.keyboard.setInput("Hello World!");

inputSetPromise.then((result) => {
  console.log("Input set");
});

dispatch

Send a command to all simple-keyboard instances at once (if you have multiple instances).

this.keyboard.dispatch(instance => {
  instance.setOptions({
    buttonTheme: [
      {
        class: "myClass",
        buttons: `a b c`
      }
    ]
  })
});

This is a port of the simple-keyboard feature of the same name. If you'd like to use a more react-like approach to sending props to many instances, you can use shared props like so:

let sharedProps = {
  layoutName: this.state.layoutName,
  onChange: input => this.onChange(input),
  onKeyPress: button => this.onKeyPress(button),
};

// Keyboard 1
<Keyboard {...sharedProps} />

// Keyboard 2
<Keyboard {...sharedProps} />

This way you can update your desired instances at the same time using this.setState.

Q&A / Use-cases

Multiple simple-keyboard instances: Setting a baseClass

Set the baseClass option to add a unique identifier to each of your simple-keyboard instances. If not set, a random baseClass will be used (e.g.: simplekeyboard_id-qeu5wu to differentiate your instance from others you may spawn).

Using several inputs

Set the inputName option for each input you want to handle with simple-keyboard.

For example:

// Tell simple-keyboard which input is active
setActiveInput = (event) => {
  this.setState({
    inputName: event.target.id
  });
}

// When the inputs are changed
// (retrieves all inputs as an object instead of just the current input's string)
onChangeAll = (input) => {
  this.setState({
    input: input
  }, () => {
    console.log("Inputs changed", input);
  });
}

render(){
  return (
    <div>
      <input id="input1" onFocus={this.setActiveInput} value={this.state.input['input1'] || ""}/>
      <input id="input2" onFocus={this.setActiveInput} value={this.state.input['input2'] || ""}/>

      <Keyboard
        ref={r => this.keyboard = r}
        inputName={this.state.inputName}
        onChangeAll={inputs => this.onChangeAll(inputs)}
        layoutName={this.state.layoutName}
      />
    </div>
  );

See full example.

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.

How to syncronize multiple instances of simple-keyboard

You can run multiple instances of simple-keyboard. To keep their internal inputs in sync, set the syncInstanceInputs option to true. If you want to send a command to all your simple-keyboard instances at once, you can use the dispatch method.

Why is the caps lock button working like shift button?

For the sake of simplicity, caps lock and shift do the same action in the main demos. If you'd like to show a different layout when you press caps lock, check out the following demo:

Demo

Live demos

https://franciscohodge.com/simple-keyboard/demo

To run demo on your own computer

• Clone this repository
• npm install
• npm start
• Visit http://localhost:3000/

Other versions

• Vanilla JS - simple-keyboard

Contributing

PR's and issues are welcome. Feel free to submit any issues you have at: https://github.com/hodgef/react-simple-keyboard/issues