Simulate key presess.
Currently only supports EN-US keyboard layout.
The key point of this library is mimicking a real keyboard so you can't press a key that is already pressed down and you cannot release a key that is not pressed down.
Holding the Shift
key makes the following key presses generate the alternative values for the relevant keys (pressing 2
while shift is down generates @
instead).
CapsLock
andNumLock
that when areON
generate alternative values are not supported yet in a similar way.
Also, holding a modifier key down (Control
, Alt
, Shift
, Meta
) updates following events accordingly (e.g. ev.ctrlKey = true
).
TODO: add supported key list
$ npm install keyboard-simulator
import {KeyboardSimulator} from 'keyboard-simulator`;
const kbSim = new KeyboardSimulator();
kbSim.keyDown('A');
kbSim.keyUp('A');
kbSim.keyPress('B');
const kbSim = new KeyboardSimulator(contextElement = document);
The context element is the element that dispatches the following keyboard events.
The default is document
. Returns a KeyboardSimulator
instance that has the following methods:
.keyDown()
.keyUp()
.keyPress()
.holdKey()
.releaseAll()
.setContextElement()
.reset()
Dispatches one or more keydown
events of given keys. Returns a boolean (or an array of booleans if passed in multiple keys), which is the result of .dispatchEvent()
. MDN dispatchEvent docs.
kbSim.keyDown('A');
kbSim.keyDown('X', 'Y', 'Z');
The instance tries to simulate a real physical keyboard so when a key is already pressed down, trying to press it again throws an error:
kbSim.keyDown('A');
kbSim.keyDown('A'); // ERROR
Dispatches one or more keyup
events of given keys. Returns a boolean (or an array of booleans if passed in multiple keys), which is the result of .dispatchEvent()
. MDN dispatchEvent docs.
kbSim.keyUp('A');
kbSim.keyUp('X', 'Y', 'Z');
The instance tries to simulate a real physical keyboard so when a key is not pressed down, trying to release it with .keyUp()
throws an error:
kbSim.keyUp('A');
kbSim.keyUp('A'); // ERROR
Dispatches keydown
followed by keyup
events for each given key. Returns an array of two booleans (per key, one for the keydown
event and one for keyup
) or an array of array of two booleans if passed in multiple keys.
kbSim.keyPress('A');
kbSim.keyPress('A', 'B', 'C');
Simulates holding a key down by dispatching multiple keydown
events for the same key with the repeat
property set to true
. Returns a boolean, which is the result of .dspatchEvent docs)
. MDN dispatchEvent
.
kbSim.keyDown('A', 'B', 'C');
kbSim.holdKey('C', 3);
Dispatches keyup
events for all the keys that are pressed down in a reversed order of which they were pressed down (first down = last to be released)
kbSim.keyDown('A', 'B', 'C');
kbSim.releaseAll(); // keyup C, B, A
Sets a new context element to dispatch following events.
const kbSim = new KeyboardSimulator(); // `document` is the default
kbSim.keyPress('A'); // document.dispatchEvent()
kbSim.setContextElm(myDiv);
kbSim.keyPress('A'); // myDiv.dispatchEvent()
The instance keeps track of pressed keys. Calling .reset()
clears the records but does not change the context element.
kbSim.keyDown('A');
kbSim.keyDown('A'); // ERROR - key 'A' is already pressed down
kbSim.reset();
kbSim.keyDown('A'); // OK