Documentation

Usage

Check out the usage instructions at the “Getting Started” page.

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',
  ...
}}

mergeDisplay

By default, when you set the display property, you replace the default one. This setting merges them instead.

mergeDisplay={true}

display={{
  '{bksp}': 'delete',
  '{enter}': 'submit',
}}

// Result:
{
  '{bksp}': 'delete'
  '{enter}': 'submit',
  '{shift}': 'shift', // < Merged from default among others
  ....
}

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}

useMouseEvents

As of react-simple-keyboard 1.18.0, PointerEvents are used on browsers that support it. However, if you wish to fall back to the previous mouse event logic, you can use this option.

useMouseEvents={true}

useTouchEvents

As of react-simple-keyboard 1.18.0, PointerEvents are used on browsers that support it. However, if you wish to only support touch events, you can use this option.

useTouchEvents={true}

autoUseTouchEvents

This enables the option useTouchEvents automatically on touch capable devices.

autoUseTouchEvents={true}

preventMouseDownDefault

Prevents loss of input focus from clicking simple-keyboard buttons.

preventMouseDownDefault={false}

stopMouseDownPropagation

Stops pointer down events on simple-keyboard buttons from bubbling to parent elements.

stopMouseDownPropagation={false}

disableCaretPositioning

Disables caret positioning, meaning that characters will always be added/removed at the end of the string.

disableCaretPositioning={false}

useButtonTag

Render buttons as <button> elements instead of the default <div> elements.

useButtonTag={false}

newLineOnEnter

Specifies whether clicking the “ENTER” button will input a newline (\n) or not.

newLineOnEnter={false}

tabCharOnTab

Specifies whether clicking the “TAB” button will input a tab character (\t) or not.

tabCharOnTab={true}

inputName

Allows you to use a single simple-keyboard instance for several inputs.

inputName={"default"}

maxLength

Restrains react-simple-keyboard’s input to a certain length. This should be used in addition to the input element’s maxlength attribute.

// Applies to all internal inputs
maxLength={5}

// Specifies different limiters for each input set, in case you are using the "inputName" option
maxLength={{
  'default': 5,
  'myFancyInput': 10
}}

inputPattern

Restrains simple-keyboard’s input to a certain regular expression. This means that if a key doesn’t match the regex, it will be ignored. If you’re looking for input validation instead, check the docs entry here.

// Applies to all internal inputs
inputPattern={/^\d+$/}

// Use an expression for a specific input, in case you are using the "inputName" option
inputPattern={{
  'default': /^\d+$/,
  'myFancyInput': /^[a-zA-Z]+$/
}}

Note: This option is used to ignore keys that don’t match a certain regular expression. For input validation, click here.

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.

baseClass={"myBaseClass"}

disableRowButtonContainers

When set to true, this option disables the button grouping functionality added in react-simple-keyboard 1.20.0.

disableRowButtonContainers={false}

syncInstanceInputs

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

syncInstanceInputs={false}

physicalKeyboardHighlight

Enable highlighting of keys pressed on physical keyboard.

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}

 

Note: If you are having issues with this prop, make sure simple-keyboard is not being re-rendered unintentionally (click for details).

physicalKeyboardHighlightTextColor

Define the text color that the physical keyboard highlighted key should have. Used when physicalKeyboardHighlight is set to true.

physicalKeyboardHighlightTextColor={"white"}

physicalKeyboardHighlightBgColor

Define the background color that the physical keyboard highlighted key should have. Used when physicalKeyboardHighlightis set to true.

physicalKeyboardHighlightBgColor={"#9ab4d0"}

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)}

onRender

Executes the callback function every time simple-keyboard is rendered (e.g: when you change layouts).

onRender={() => console.log("simple-keyboard refreshed")}

beforeFirstRender

Executes the callback function before the first simple-keyboard render.

beforeFirstRender={() => console.log("simple-keyboard will render for the first time")}

beforeRender

Executes the callback function before a simple-keyboard render.

beforeRender={() => console.log("simple-keyboard will render")}

onInit

Executes the callback function once simple-keyboard is rendered for the first time (on initialization).

onInit={() => console.log("simple-keyboard initialized")}

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

Note: This section has been changed as of react-simple-keyboard 1.19.0

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.keyboardRef = r}
  [...]
/>

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

clearInput

Clear the keyboard’s input.

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

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

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

setInput

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

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

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

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

dispatch

This was a port of the simple-keyboard feature of the same name. It has been removed from this react version in favor of a react-like approach.

To send props to several instances at once, 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.

getButtonElement

Get the DOM Element of a button. If there are several buttons with the same name, an array of the DOM Elements is returned.

this.keyboardRef.keyboard.getButtonElement('a'); // Gets the "a" key as per your layout
this.keyboardRef.keyboard.getButtonElement('{shift}') // Gets all keys with that name in an array

addButtonTheme

Adds an entry to the buttonTheme. Basically a way to add a class to a button.

Unlike the buttonTheme property, which replaces entries, addButtonTheme creates entries or modifies existing ones.

this.keyboardRef.keyboard.addButtonTheme("a b c {enter}", "myClass1 myClass2");

removeButtonTheme

Removes an entry to the buttonTheme. Basically a way to remove a class previously added to a button through buttonTheme or addButtonTheme.

Unlike the buttonTheme property, which replaces entries, removeButtonTheme removes entries or modifies existing ones.

this.keyboardRef.keyboard.removeButtonTheme("b c", "myClass1 myClass2");

Last Updated:

Having issues or questions?

Check out the Q&A/Use-cases page

Support development of this library: